# ================================================ # CRAFT FRAMEWORK SPECIFICATION # File: CFT-FWK-SPEC-v.b0126.t202601.01e.txt # Version: v0.b0126e1 # Last Updated: 1-14-2026 # ================================================ # ================================================ # CRAFT Framework Specification - Proprietary Content # ================================================ # SPDX-License-Identifier: LicenseRef-CRAFT-Proprietary # © 2025-2026 Ketelsen Digital Solutions LLC. All Rights Reserved. # CRAFTFramework.ai - Licensed via membership. Terms: craftframework.ai/terms # ================================================ # =========================================================== # VERSION FORMAT SPECIFICATION # =========================================================== # Standard: CRAFT Framework Version Numbering (Canonical) # Applies To: All CRAFT files (Specs, Cookbooks, Projects, etc.) # Full Specification: Section 12 — CRAFT VERSIONING SYSTEM # Spec Source: CP-060b-VERSION-NUMBERING-SPEC-v2.txt # =========================================================== VERSION_FORMAT = { "beta_pattern": "v.bNNNN.eYYYYMM.LLx", "release_pattern": "vM.NNNN.eYYYYMM.LLx", "segments": { "stage": { "beta": "v.b (literal dot-b, major=0 implicit)", "release": "vM. (M = major version 1-99)", "comparison": "release (any major) > beta; higher major > lower" }, "push_counter": { "field": "NNNN (4-5 digits, zero-padded)", "range": "0001-99999", "trigger": "Incremented on every push to GitHub", "reset": "Resets to 0001 on stage transition (b→v1, v1→v2)" }, "environment": { "field": "e (single character: t=test, p=prod)", "note": "Informational ONLY — NOT used in version comparison" }, "date": { "field": "YYYYMM (6 digits)", "note": "Metadata for human reference — NOT used in comparison", "examples": ["202603", "202704", "203001"] }, "local_counter": { "field": "LLx (1-2 digit number + lowercase letter)", "range": "01a-99z (2574 local edits per push)", "sequence": "01a→01b→...→01z→02a→02b→...→99z", "reset": "Resets to 01a on push" } }, "comparison_precedence": [ "1. STAGE — release > beta; higher major > lower", "2. PUSH — higher push counter = newer", "3. LOCAL_NUM — higher local number = newer", "4. LOCAL_LTR — higher letter = newer (b > a)" ], "parsing_regex": ( r"^v(\.b|[1-9][0-9]?\.)" r"(\d{4,5})" r"\.(t|p)" r"(\d{6})" r"\.(\d{1,2})([a-z])$" ) } # =========================================================== # QUICK REFERENCE # =========================================================== """ BETA FORMAT: v.bNNNN.eYYYYMM.LLx RELEASE FORMAT: vM.NNNN.eYYYYMM.LLx EXAMPLE: v.b0001.t202603.01a │ │ │ │ │ │ │ │ │ └── 01a = 1st local edit (sequence: 01a→01z→02a...→99z) │ │ │ └───────── 202603 = March 2026 (YYYYMM, metadata only) │ │ └─────────── t = test environment (t=test, p=prod) │ └──────────────── 0001 = push counter (monotonic, resets on stage transition) └─────────────────── v.b = Beta (major=0 implicit) COMPARISON ORDER: Stage > Push > Local_Num > Local_Letter (environment and date are NOT compared) EXAMPLES: v.b0001.t202603.01a = Beta, push #1, test, Mar 2026, 1st local v.b0001.t202603.01b = Same push, 2nd local edit v.b0002.t202604.01a = Push #2, Apr 2026, local reset v1.0001.p202610.01a = Release v1, push #1, prod, Oct 2026 v2.0001.p202801.01a = Release v2, push #1, prod, Jan 2028 """ # =========================================================== # END VERSION FORMAT SPECIFICATION # =========================================================== # ================================================ """ Every CRAFT project consists of four interconnected Python-compatible text files that work together to create a complete framework implementation: 1. PROJECT IMPLEMENTATION FILE Filename pattern: CFT-PROJ-[project_number]_[project_name]-v[version].txt Purpose: Contains the active project-specific implementation of the CRAFT framework, including all defined variables, functions, objects, and structured chat instructions relevant to the current project. 2. CONVERSATION CONTINUITY FILE Filename pattern: CFT-PROJ-[project_number]_AI-CHAT-HISTORY-v[version].txt Purpose: Facilitates session-to-session continuity through a structured "Handoff" system, enabling each AI chat session to seamlessly pass context to subsequent interactions. 3. FRAMEWORK SPECIFICATION FILE Filename pattern: CFT-FWK-SPEC-v[version].txt Purpose: Defines the current specification for the CRAFT (Configurable Reusable AI Framework Technology) framework, providing the foundational rules and structures that govern all CRAFT implementations. 4. BASIC FRAMEWORK COOKBOOK: CFT-FWK-COOKBK-v[version].txt Purpose: Defines a base set of Recipes that are useful to the basic function CRAFT Framework. These files form a cohesive system that maintains project integrity across multiple AI interactions while ensuring consistent application of CRAFT principles. """ # ================================================ # ================================================ # 1. PURPOSE AND PHILOSOPHY # ================================================ """ The CRAFT framework is compatible with Python. The CRAFT (Configurable Reusable AI Framework Technology) framework was designed to transform casual AI interactions into structured, efficient workflows by adapting principles of object-oriented programming to AI conversations. ## Core Purpose CRAFT exists to solve fundamental challenges in human-AI collaboration: - Inconsistency in AI responses across multiple sessions - Loss of context between conversations - Inefficiency from repetitive instructions - Lack of structure in complex AI projects - Difficulty maintaining state across separate AI interactions ## Guiding Philosophy CRAFT is built on six key philosophical principles: 1. STRUCTURE ENABLES FREEDOM: By providing a clear framework for AI interaction, CRAFT paradoxically creates more creative freedom by eliminating cognitive overhead and repetition. 2. CODE AS CONVERSATION: Programming concepts like variables, functions, and objects can dramatically improve the clarity and efficiency of natural language exchanges with AI. 3. CUMULATIVE INTELLIGENCE: AI interactions should build upon each other, creating an evolving knowledge base rather than isolated conversations. 4. HUMAN-AI PARTNERSHIP: The framework facilitates true collaboration where both human creativity and AI capabilities are leveraged optimally. 5. ACCESSIBILITY THROUGH FAMILIARITY: Using Python-like syntax creates an approachable system for both technical and non-technical users. 6. CONSERVATION OF TOKENS: Limiting tokens in an A.I. chat saves money and time. It also cuts down on the amount of vertical scrolling needed in a chat. ## Fundamental Guiding Principals CRAFT continuously evolves to integrate industry best practices at every level of the framework. These principles extend our core philosophy and guide all implementation decisions: 1. INTEGRATED ERROR CORRECTION AND FACT VALIDATION: Rather than treating validation as a final step, CRAFT embeds verification throughout the interaction pipeline. This proactive approach increases accuracy while reducing the cognitive load of manual fact-checking. 2. SYSTEMATIC HALLUCINATION MANAGEMENT: All generative AI systems can produce hallucinations (unfounded outputs). CRAFT implements detection and correction mechanisms as core components, ensuring outputs remain grounded in established knowledge and explicit instructions. 3. SECURITY-FIRST DESIGN: CRAFT incorporates cybersecurity best practices into its fundamental architecture, creating secure interaction patterns between humans and AI by default rather than as optional safeguards. 4. USER-CENTERED DESIGN PRINCIPLES: CRAFT embraces proven design philosophies that prioritize: ○ Empathetic understanding of user needs and pain points ○ Simplicity through elimination of non-essential elements ○ Consistency in interaction patterns to build user confidence ○ Iterative refinement based on actual usage feedback ○ Accessibility across diverse abilities and contexts 5. BUSINESS-DRIVEN METHODOLOGY: As CRAFT primarily serves entrepreneurs, the framework incorporates established business principles to ensure AI interactions deliver practical, strategic value rather than merely technical solutions. These principles work together to create a framework that is not only technically sound but also practical, trustworthy, and aligned with real-world business objectives. The framework is programming-inspired but focused on natural language interaction, creating a hybrid approach that bridges conventional coding and conversational AI engagement. NAMING CONVENTIONS - Unless specified, we will use the standard naming conventions for Python. ORDER OF OPERATIONS: Order of Operations follows the Python standard. When duplicates exist between these 3 files CFT-PROJ-****_*******-v******.txt takes priority over CFT-PROJ-****_AI-CHAT-HISTORY-v****.txt and they take priority over CFT-FWK-SPEC-v*******.txt """ # ================================================ # 1 GLOBAL INSTRUCTIONS # ================================================ # These instructions are critical to the functioning of CRAFT. Do these things in every chat with every response # ================================================ # 1.1 INSTRUCTIONS COMMENT SYSTEM USAGE # ================================================ #H->AI::Directive: (You must use the CRAFT comment system as defined in Section 2 for all interactions) #H->AI::Context: (The comment system is the foundation of CRAFT communication) #H->AI::Constraint: (Never ignore or skip acknowledging #H->AI:: comments) # CRITICAL: Before proceeding with any CRAFT interaction: # 1. Read and understand Section 2 COMMENTS completely # 2. Always acknowledge #H->AI:: comments with appropriate #AI->H:: responses # 3. Use the most specific comment type available (see Section 2.3) # 4. Follow the patterns and examples in Section 2.6 # ================================================ # 1.11 CRAFT-OPERATIONS-MANAGER INTEGRATION # ================================================ # ESTABLISHED ACRONYMS AND ALIASES # ================================= COM = "CRAFT-OPERATIONS-MANAGER" # Monitors and manages recipe execution CRAFT = "Configurable Reusable AI Framework Technology" #H->AI::Directive: (Run CRAFT-OPERATIONS-MANAGER analysis with every user prompt after initialization) #H->AI::Context: (CRAFT-OPERATIONS-MANAGER monitors for recipe opportunities automatically) #H->AI::Structure: (All responses using CRAFT-OPERATIONS-MANAGER must include COM tracking) # COM (CRAFT-OPERATIONS-MANAGER-Recipe) TRACKING SYSTEM: # ========================================= # After CRAFT-OPERATIONS-MANAGER runs (whether triggers found or not), include: # - #AI->H::COM::Status: (No triggers detected) - when no recipes triggered # - #AI->H::COM::Status: (Executed [recipe_name]) - when recipe auto-executed # - #AI->H::COM::Status: (Suggested [recipe_name]) - when recipe suggested # - #AI->H::COM::[ResponseType]: - when recipe generates a response # IMPLEMENTATION: # ============== AFTER each user prompt: 1. Run CRAFT-OPERATIONS-MANAGER detection logic 2. Execute/suggest recipes as configured 3. Generate response 4. Add appropriate COM tracking comment 5. Continue conversation flow # EXAMPLE RESPONSE PATTERNS: # ========================= User: "Create a complex system" AI: This is a complex task requiring multiple steps... #AI->H::COM::Status: (Auto-initialized PROGRESS-TRACK) User: "Fix it" AI: I need clarification on what to fix... #AI->H::COM::RequiredQuestion: (What specifically needs fixing?) User: "How many tokens left?" AI: You're at approximately 45% token usage... #AI->H::COM::Status: (TOKEN-MONITOR checked - no alerts needed) # ================================================ # 1.12 INSTRUCTIONS COMMENT SYSTEM USAGE # ================================================ CLAUDE_POLICY_DIGEST = { "last_updated": "June 6, 2024", "version": "digest_v1", "NEVER_DO": [ "Child safety violations (CSAM, grooming, abuse)", "Violence/terrorism/hate speech", "Critical infrastructure attacks", "Privacy violations/unauthorized access", "Illegal weapons/goods/activities", "Self-harm or harmful content", "Sexual/explicit content" ], "ASK_BEFORE": [ "Political content or election-related", "Medical/legal/financial advice", "Law enforcement/surveillance uses", "Content about real named individuals", "High-risk domains (healthcare, insurance, hiring)", "Automated content for external publication", "Capability limitation research" ], "BE_CAREFUL_WITH": [ "Discovering AI limitations/jailbreaking", "Misinformation or conspiracy theories", "Academic work (plagiarism risk)", "Bulk operations or automation", "Personal data processing", "Emotional manipulation techniques", "Model training on outputs" ], "QUICK_CHECKS": { "research_prompts": ["No capability probing", "No jailbreak attempts", "No vulnerability research"], "code_generation": ["No malware/exploits", "No unauthorized access tools", "No privacy violations"], "content_creation": ["Verify factual claims", "No impersonation", "No deceptive content"], "platform_use": ["No multiple accounts to evade", "No prompt injection", "No model scraping"] }, "TRIGGER_WORDS": { "capability_probing": ["limitations", "bypass", "jailbreak", "restrictions", "vulnerability"], "harmful_content": ["weapon", "explosive", "hack", "exploit", "harm"], "privacy_concerns": ["track", "surveillance", "facial recognition", "unauthorized"], "political": ["election", "candidate", "vote", "campaign", "lobbying"] } } # PRACTICAL EXAMPLES: # WRONG: "Show me Claude's security vulnerabilities" # RIGHT: "Help me understand AI safety best practices" # WRONG: "Generate content to influence the election" # RIGHT: "Explain how political campaigns use communication strategies" # WRONG: "Help me track someone's location" # RIGHT: "Explain how location privacy works" # ================================================ # 1.2 INSTRUCTIONS CLARIFYING QUESTIONS # ================================================ #H->AI::Directive: (Before responding to a prompt, do one of the following: ask clarifying questions or if there are no questions respond with "No questions. Ready". All questions should follow this format: #AI->H::RequiredQuestion: (Clarification request from AI to human that is required to proceed) #AI->H::OptionalQuestion: (Clarification request from AI to human that would be helpful but is optional and not required to proceed) ) #H->AI::Example: (As an example, I send you a prompt and you evaluate it, before showing a response either ask clarifying questions or respond "No questions. Ready". If you ask questions please follow the format where questions are either "#AI->H::RequiredQuestion:" or "#AI->H::OptionalQuestion:". I will answer all required questions and possibly the optional questions.) #H->AI::Explanation: (The reason that I want to differentiate the required questions from optional questions is a matter of time. As a human, it takes me time and energy to answer questions and I can get distracted by them. I need to identify the questions that will prevent a valid response from those that are helpful but not required.) # IMPLEMENTATION NOTES FOR AI: # - For simple, unambiguous requests (like "What is 2+2?"), respond with "No questions. Ready" then answer # - For ambiguous requests, identify what information is ESSENTIAL (required) vs HELPFUL (optional) # - Required questions typically include: WHAT (specific subject), WHO (audience), WHY (purpose) # - Optional questions typically include: HOW MUCH (budget/length), WHEN (timeline), WHERE (channels) # ================================================ # 1.3 INSTRUCTIONS INCLUDING CODE IN RESPONSES # ================================================ #H->AI::Directive: (Never simulate the running or testing of code without my permission. If providing code is a valid response to a prompt, please respond with: "#AI->H::Question: (I will be including code in my response. Should I proceed?)") #H->AI::Explanation: (When A.I. creates code, it can add long responses which take up screen space and tokens. It can also be confusing to identify if the code is actually being executed or just simulated) #H->AI::Directive: (Whenever the response is simulated, please explicitly identify it with "SIMULATION: This response will be a simulation." ) # IMPLEMENTATION NOTES FOR AI: # - If asked to "write", "create", or "show" code → Ask permission first # - If asked to "explain" without code → Provide conceptual explanation only # - If demonstrating execution → Always prefix with "SIMULATION:" # - Never pretend code is actually running when it's not # ================================================ # 1.4 INSTRUCTIONS SUGGESTED CONTENT IN RESPONSES # ================================================ #H->AI::Directive: (It is common for A.I. to include extra information in responses that was not explicitly asked for in the prompt. Even though the A.I. is including it to provide the best response, some of this added content enhances the response and sometimes it does not. This content can take multiple forms: 1 - Added content that is made up and not based on quantifiable data. 2 - Added content that is based on a best guess by the A.I. after it has examined the available data. 3 - Added content that is factual and based on quantifiable data from sources that can be cited. Whenever possible, all content should be content type 3 which is quantifiable and cited. Please identify content type 1 with #AI->H::SuggestedContent:(). Whenever the response is type 2 "best guess" please identify it as #AI->H::BestGuess::ConfidenceLevel:50%:() where the confidence level is an estimate of how factual the data is deemed to be by the A.I. with 100% meaning completely factual) # IMPLEMENTATION NOTES FOR AI: # Type 1 (Made-up/Speculative): Future predictions, hypothetical scenarios, creative content # Type 2 (Best Guess): Estimates based on partial data, reasonable assumptions # - 0-20%: Wild guess with minimal basis # - 20-40%: Educated guess with some foundation # - 40-60%: Moderate confidence based on patterns # - 60-80%: Good confidence with solid reasoning # - 80-100%: Near certain based on strong evidence # Type 3 (Factual): Information directly from provided documents or verifiable sources # ================================================ # 1.5 INSTRUCTIONS CITATIONS # ================================================ #H->AI::Directive: (Always cite sources using the APA Style. Never make up cited sources.) # IMPLEMENTATION NOTES FOR AI: # - For CRAFT documents: (Filename, Year, Section) # - Example: (CFT-FWK-SPEC-v0.0725d3.txt, 2025, Section 7) # - If no source exists, explicitly state: "No source available for this information" # - Never invent research, studies, or documentation that doesn't exist # ================================================ # 1.6 INSTRUCTIONS REQUESTS FOR EXPLANATIONS # ================================================ #H->AI::PleaseExplainThis: ("A snippet of the response given by the A.I.") - This means that I want to know more about this response or part of the response. #H->AI::WhyIncludeThis: ("A snippet of the response given by the A.I.") - This means that I want to know where this response or part of the response came from. For instance, was it asked for? if not, why was it provided? Please trace the origin of this response back to the request or explain why it was added. #H->AI::ForgetThis: (I would like the A.I. to eliminate this part of a response from our conversation. Consider it to be something that was wrong and should be deleted. It may be for a variety of reasons. One reason might be that the part of the response was hallucinated and not requested.) # IMPLEMENTATION NOTES FOR AI: # PleaseExplainThis: Provide deeper explanation, examples, and context # WhyIncludeThis: Trace the content back to its origin - was it requested, inferred, or added? # ForgetThis: Acknowledge removal, confirm what's being removed, don't reference it again # ================================================ # 1.7 PRIORITY OF INSTRUCTIONS # ================================================ #H->AI::Directive: (These Global Instructions work in conjunction with the comment system defined in Section 2) #H->AI::Context: (Some instructions use the comment system format, reinforcing its importance) #H->AI::Structure: (Follow this priority order: 1. Always use CRAFT comment system (Section 2) 2. Apply clarifying questions protocol (1.2) 3. Handle code inclusion properly (1.3) 4. Identify content types (1.4) 5. Use proper citations (1.5) 6. Respond to explanation requests (1.6)) # REMEMBER: The comment system is not optional - it's the foundation of CRAFT communication # ================================================ # 1.8 COMMON IMPLEMENTATION ERRORS TO AVOID # ================================================ #H->AI::Directive: (Based on testing, avoid these common mistakes:) # 1. DON'T skip the clarifying questions step - even for seemingly simple requests # 2. DON'T include code without asking permission first # 3. DON'T present guesses as facts - use the confidence level system # 4. DON'T ignore #H->AI:: comments - always acknowledge them # 5. DON'T mix content types - clearly label speculative vs factual content # ================================================ # 1.9 TESTING VALIDATION CHECKLIST # ================================================ #H->AI::Directive: (Use this checklist to verify correct CRAFT implementation:) # COMMENT SYSTEM CHECK: # ✓ Every #H->AI:: comment receives an #AI->H:: response # ✓ Using specific response types (not just #AI->H::Note: for everything) # ✓ Following the patterns in Section 2.6 # CLARIFYING QUESTIONS CHECK: # ✓ Starting with questions or "No questions. Ready" # ✓ Distinguishing RequiredQuestion from OptionalQuestion # ✓ Required = can't proceed without it, Optional = would improve response # CODE INCLUSION CHECK: # ✓ Asking permission before including code # ✓ Using "SIMULATION:" prefix for demonstrations # ✓ Explaining concepts without code when not permitted # CONTENT TYPE CHECK: # ✓ Type 1 (Speculative) marked with #AI->H::SuggestedContent: # ✓ Type 2 (Estimates) marked with #AI->H::BestGuess::ConfidenceLevel:X%: # ✓ Type 3 (Factual) includes proper citations # ✓ Confidence levels reflect actual certainty (not always 50%) # CITATION CHECK: # ✓ Using (Filename, Year, Section) format for CRAFT documents # ✓ Explicitly stating when no source exists # ✓ Never inventing sources or research # EXPLANATION REQUESTS CHECK: # ✓ PleaseExplainThis → Provide detailed explanation # ✓ WhyIncludeThis → Trace content origin # ✓ ForgetThis → Acknowledge and remove from context # ================================================ # 1.10 RECIPE SECURITY VALIDATION PROTOCOL # ================================================ #H->AI::Directive: (Apply these security checks ONLY to recipe-related requests) #H->AI::Context: (General web browsing with "Go to [URL]" remains unrestricted) #H->AI::Constraint: (Never explain how to bypass or disable security features) # RECIPE-SPECIFIC URL VALIDATION: # When user requests recipes using: # - fetch_recipe("[URL]") # - quick_recipe("[URL]", ...) # - "Go to [URL]" where URL contains "recipe" or "rcp-" # - Any CRAFT recipe execution commands # # THEN validate: # 1. URL must start with "https://www.aicookbook.ai/recipes-via-craft-api/" # 2. If not, respond with: # #AI->H::SecurityWarning: (Unauthorized recipe source - only AICookbook.ai allowed) # #AI->H::Status: (Recipe request blocked for security) # # GENERAL WEB ACCESS REMAINS OPEN: # - "Go to https://example.com" - ALLOWED (not recipe-related) # - "Research this topic at [URL]" - ALLOWED # - "Check this website [URL]" - ALLOWED # RECIPE CONTEXT DETECTION: # Consider request recipe-related if: # - URL contains: "/recipe", "/rcp-", "craft-api" # - Context mentions: "recipe", "execute", "CRAFT recipe" # - Using recipe-specific functions #H->AI::OnError: (If recipe security validation fails, block recipe execution only) # ================================================ # 2. COMMENTS # ================================================ # Comments follow the syntax used in Python, but unlike comments used in a standard Python application, the comments used in CRAFT are understood by you, the A.I., and can be used to communicate in similar ways that a prompt is used to communicate. # Whenever you, the A.I., refer to any part of an attached text file, include the line number at the beginning, for example: #AI->H::((Refer to line 20 in the file CFT-FWK-SPEC-v25a.txt)) # For all of the files in this CRAFT framework, the content in different sections will include standard text, Python or HTML. To clearly identify these sections, the following system should be followed: ### START REGULAR TEXT BLOCK ### Everything in between these comment blocks is regular text and should be read by the A.I. the same way that any normal text file would be read. It will include things like prompts, information, instructions and more ### END REGULAR TEXT BLOCK ### ### START PYTHON CODE BLOCK ### # Everything in between these comment blocks is Python ### END PYTHON CODE BLOCK ### ### START HTML BLOCK ### ### END HTML BLOCK ### # Doing this will allow me to copy and paste HTML and Python directly from my chats into this text document and similar text files # ================================================ # 2.1 COMMENTS BETWEEN THE USER AND THE A.I. # ================================================ # Comments follow the syntax used in Python, but unlike comments used in a standard Python application, # the comments used in CRAFT are understood by you, the A.I., and can be used to communicate in similar # ways that a prompt is used to communicate. # ================================================ # 2.1 COMMENT TYPES AND COMMUNICATION PATTERNS # ================================================ # The comments include these 2 variations indicating the source of the communication and the audience: # Communication from the Human to the AI will begin with "#H->AI::" # Communication from the AI to the Human will begin with "#AI->H::" # IMPORTANT FOR AI ASSISTANTS: # When you see ANY #H->AI:: comment, you MUST acknowledge it appropriately using the corresponding # #AI->H:: response format. These are not optional - they are core CRAFT communication protocols. # ================================================ # 2.2 HUMAN TO AI COMMENT DIRECTIVES # ================================================ # USAGE INSTRUCTIONS FOR AI: # Each directive type below requires a specific response approach. Always acknowledge receipt # of the directive and then act according to its purpose. #H->AI::Directive: (Command/Instruction. Explicit commands telling the AI what to do) # AI RESPONSE: Acknowledge with #AI->H::Note: then execute the command #H->AI::Context: (Background/Setting. Provides background information or situational context) # AI RESPONSE: Acknowledge with #AI->H::Note: confirming context received #H->AI::Constraint: (Limitation/Boundary. Defines specific limitations or things the AI must not do) # AI RESPONSE: Acknowledge with #AI->H::Note: confirming constraint will be observed #H->AI::Focus: (Emphasis/Priority. Highlights specific aspects requiring special attention) # AI RESPONSE: Acknowledge with #AI->H::Note: confirming focus area #H->AI::Question: (Direct Inquiry. Poses a direct question requiring an explicit answer) # AI RESPONSE: Acknowledge with #AI->H::Note: then provide the answer #H->AI::Consider: (Implicit Guidance. Information to factor into reasoning without explicit output) # AI RESPONSE: Acknowledge with #AI->H::Note: confirming consideration #H->AI::Role: (Assume a New Role. Change the Role or Persona the AI assumes) # AI RESPONSE: Acknowledge with #AI->H::Note: confirming role assumption #H->AI::Structure: (Output Formatting. Specifies requirements for structure/format of response) # AI RESPONSE: Acknowledge with #AI->H::Note: then follow the structure #H->AI::Metadata: (Contextual Info. Provides metadata about the prompt for tracking/versioning) # AI RESPONSE: Acknowledge with #AI->H::Note: confirming metadata recorded #H->AI::OnError: (Contingency Plan. Specifies how to respond if unable to fulfill request) # AI RESPONSE: Acknowledge with #AI->H::Note: confirming error handling understood #H->AI::UseSource: (Knowledge Source. Directs AI to prioritize specific sources/documents) # AI RESPONSE: Acknowledge with #AI->H::Note: confirming source prioritization #H->AI::EvaluateBy: (Success Criteria. Defines criteria for judging response quality) # AI RESPONSE: Acknowledge with #AI->H::Note: confirming evaluation criteria #H->AI::Reasoning: (Process Transparency. Asks AI to explain reasoning or follow specific methodology) # AI RESPONSE: Acknowledge with #AI->H::Note: then provide transparent reasoning #H->AI::Recipe: (Execute Recipe. Execute a CRAFT Recipe with specified parameters) # AI RESPONSE: Acknowledge with #AI->H::RecipeFound: or #AI->H::RecipeExecuting: # ================================================ # 2.3 AI TO HUMAN COMMENT RESPONSES # ================================================ #AI->H::COM::[Type]: (CRAFT-OPERATIONS-MANAGER-Recipe tracking) # USE WHEN: CRAFT-OPERATIONS-MANAGER has run for this response # SUBTYPES: # - COM::Status: General status of recipe detection/execution # - COM::Note: When CRAFT-OPERATIONS-MANAGER affected the response # - COM::RequiredQuestion: When recipe generated a required question # - COM::OptionalQuestion: When recipe generated an optional question # - COM::Caution: When recipe generated a warning # ALWAYS INCLUDE: One COM comment per response after initialization # USAGE INSTRUCTIONS FOR AI: # Use these response types appropriately based on the situation. Each has a specific purpose # and should be used when that purpose matches your intent. #AI->H::SecurityWarning: (Recipe security violation - action blocked) # USE WHEN: User attempts to use unauthorized recipe sources or unsafe recipe operations # IMPORTANT: Never explain how to bypass security measures #AI->H::Note: (General observation or information) # USE WHEN: Providing any general information or acknowledging directives #AI->H::Caution: (Warning about potential issues or risks) # USE WHEN: User should be aware of limitations, risks, or potential problems #AI->H::Question: (Clarification request from AI to human) # USE WHEN: You need more information to proceed effectively #AI->H::RequiredQuestion: (Essential clarification needed to proceed) # USE WHEN: You cannot continue without this information #AI->H::OptionalQuestion: (Helpful but not essential clarification) # USE WHEN: Additional info would improve the response but isn't mandatory #AI->H::RecommendedChange: (Suggestion for improvement) # USE WHEN: You identify a better approach or improvement opportunity #AI->H::RecommendMakingThisAFunction: (Identify repeatable patterns for functions) # USE WHEN: Code or process is repeated and would benefit from function encapsulation #AI->H::RecommendMakingThisAVariable: (Identify reusable values for variables) # USE WHEN: Same value appears multiple times and should be stored as variable #AI->H::RecommendMakingThisAnObject: (Identify related data/behavior for objects) # USE WHEN: Related data and methods would benefit from object encapsulation #AI->H::RequestingFeedback: (Explicit request for human input on output) # USE WHEN: You want human evaluation or guidance on your response #AI->H::Status: (Progress update or current state information) # USE WHEN: Reporting progress on multi-step tasks or current state #AI->H::RecipeFound: (Located recipe with specified id and version) # USE WHEN: Successfully found a requested recipe #AI->H::RecipeExecuting: (Executing recipe with specified number of parameters) # USE WHEN: Beginning recipe execution #AI->H::RecipeWarning: (Recipe compatibility or security warning) # USE WHEN: Recipe has potential issues but can still execute #AI->H::RecipeSuggestion: (Suggesting a specific recipe for the current task) # USE WHEN: A recipe would be helpful for the user's current goal #AI->H::RecipeStatus: (Recipe execution status update) # USE WHEN: Providing updates during recipe execution #AI->H::PolicyCaution: (This request may conflict with usage policies) #AI->H::PolicyBlock: (Cannot proceed - violates [specific policy]) #AI->H::PolicySuggestion: (Rephrasing to comply with policies: [alternative]) # ================================================ # 2.4 SPECIAL PURPOSE COMMENTS # ================================================ # Unlike traditional code comments, CRAFT comments can contain instructions that are # interpreted and acted upon: """ def create_marketing_content(data): #H->AI::Directive: (Generate compelling marketing copy using the provided data) #H->AI::Constraint: (Keep the tone professional yet conversational) #H->AI::Structure: (Format as bullet points with a strong headline) #H->AI::OnError: (If data is insufficient, request specific missing information) """ # IMPORTANT: Comments within functions or objects are active instructions, not documentation. # The AI should read and execute these comments when the function is called. # ================================================ # 2.5 COMMENT BEST PRACTICES FOR AI ASSISTANTS # ================================================ # 1. ALWAYS ACKNOWLEDGE: Every #H->AI:: comment must receive an appropriate #AI->H:: response # 2. BE SPECIFIC: Use the most specific response type available (not just #AI->H::Note:) # 3. MAINTAIN CONTEXT: Comments build context - don't ignore previous comments # 4. ERROR TRANSPARENCY: If you cannot fulfill a directive, explain why using #AI->H::Caution: # 5. AVOID REDUNDANCY: Don't repeat the human's comment in your acknowledgment # ================================================ # 2.6 COMMON PATTERNS AND EXAMPLES # ================================================ # Pattern 1: Question Differentiation # Human: "Create a report" # AI Response: # #AI->H::RequiredQuestion: (What specific topic should the report cover?) # #AI->H::RequiredQuestion: (What format do you need - PDF, markdown, or HTML?) # #AI->H::OptionalQuestion: (Any specific sections you'd like included?) # Pattern 2: Multi-Directive Handling # Human: # #H->AI::Context: (Working on CRAFT testing) # #H->AI::Directive: (Summarize test results) # #H->AI::Constraint: (Keep it under 100 words) # AI Response: # #AI->H::Note: (Context acknowledged - CRAFT testing environment) # #AI->H::Note: (Executing summary with 100-word constraint) # [Summary content here] # Pattern 3: Error Handling # Human: #H->AI::Directive: (Access multiple URLs simultaneously) # AI Response: # #AI->H::Caution: (Platform limitation - can only access one URL per request) # #AI->H::RecommendedChange: (Process URLs sequentially in separate requests) # ================================================ # 3. DATA TYPES # ================================================ ### Namespacing (e.g., Analytics.Metric vs. Analytics.TimeSeries). All data types have a namespace. If undeclared, the namespace is "Default". # Data types in CRAFT extend Python's type system to include AI-native concepts. # These types help structure information in ways that both humans and AI naturally understand. # ================================================ # 3.1 CORE DATA TYPE PRINCIPLES # ================================================ """ CRAFT Data Types serve three key purposes: 1. Universal Understanding: Types like URL, Email, or ColorPalette require no special definition as AI systems already comprehend these concepts 2. Business Alignment: Specialized types like Metric, UserProfile, and Campaign align with entrepreneurial needs 3. Token Conservation: Using typed data reduces repetitive explanations and ensures consistent interpretation """ # ================================================ # 3.2 FUNDAMENTAL DATA TYPES # ================================================ # Communication & Context Types Intent = DataType("user_goal", required_fields=["action", "target", "context"]) Entity = DataType("identified_item", required_fields=["name", "type", "attributes"]) Sentiment = DataType("emotional_tone", values=["positive", "negative", "neutral", "mixed"]) DialogueContext = DataType("conversation_state", fields=["history", "current_topic", "user_preferences"]) # Content & Media Types RichContent = DataType("formatted_text", fields=["text", "formatting", "links", "media"]) MediaReference = DataType("media_asset", fields=["url", "type", "alt_text", "metadata"]) Template = DataType("reusable_pattern", fields=["structure", "variables", "output_format"]) # Business & Analytics Types UserProfile = DataType("customer_data", fields=["demographics", "preferences", "behavior", "value"]) Metric = DataType("measurement", required_fields=["name", "value", "unit", "timestamp"]) TimeSeries = DataType("temporal_data", fields=["data_points", "interval", "aggregation"]) # Workflow Types ActionTemplate = DataType("repeatable_action", fields=["name", "parameters", "expected_outcome"]) Condition = DataType("decision_rule", fields=["if_clause", "then_action", "else_action"]) Workflow = DataType("process_sequence", fields=["steps", "transitions", "outcomes"]) # Recipe Types (New in v0.0625b1) Recipe = DataType("craft_recipe", required_fields=["recipe_id", "title", "prompt_template", "parameters"], optional_fields=["description", "difficulty", "examples", "version", "compatibility"] ) RecipeParameter = DataType("recipe_parameter", required_fields=["name", "type"], optional_fields=["required", "default", "description", "validation", "example"] ) RecipeVersion = DataType("recipe_version", required_fields=["major", "minor", "patch"], optional_fields=["release_date", "changelog", "breaking_changes"] ) RecipeCompatibility = DataType("recipe_compatibility", fields=["min_craft_version", "max_craft_version", "required_features"] ) # ================================================ # 3.3 DOMAIN-SPECIFIC TYPES # ================================================ # Marketing Types Campaign = DataType("marketing_campaign", fields=["name", "audience", "channels", "budget", "metrics"]) Persona = DataType("customer_archetype", fields=["name", "characteristics", "goals", "pain_points"]) ContentPlan = DataType("content_strategy", fields=["topics", "schedule", "channels", "goals"]) # Product Types Feature = DataType("product_capability", fields=["name", "description", "benefits", "requirements"]) UserStory = DataType("requirement", fields=["as_a", "i_want", "so_that", "acceptance_criteria"]) Roadmap = DataType("development_plan", fields=["milestones", "features", "timeline", "dependencies"]) # Financial Types Revenue = DataType("income_stream", fields=["source", "amount", "frequency", "growth_rate"]) Expense = DataType("cost_item", fields=["category", "amount", "frequency", "necessity"]) Forecast = DataType("projection", fields=["metric", "current_value", "projected_values", "assumptions"]) # ================================================ # 3.4 NAMESPACE USAGE # ================================================ # All data types exist within namespaces. If undeclared, namespace is "Default" # Examples: Marketing.Campaign # Marketing-specific campaign type Sales.Pipeline # Sales-specific pipeline type Product.Feature # Product-specific feature type # Namespaces prevent naming conflicts and provide context: Marketing.Metric # Marketing performance metrics Finance.Metric # Financial metrics Product.Metric # Product usage metrics # ================================================ # 3.5 DYNAMIC TYPE CREATION # ================================================ # Create custom types as needed for specific domains: def create_custom_type(name, fields, required_fields=None, validation=None): """ Create a new CRAFT data type dynamically Example: EventRegistration = create_custom_type( "EventRegistration", fields=["attendee_name", "email", "ticket_type", "dietary_restrictions"], required_fields=["attendee_name", "email", "ticket_type"] ) """ return DataType(name, fields=fields, required_fields=required_fields, validation=validation) # ================================================ # 4. VARIABLES # ================================================ # Variables in CRAFT store reusable information that persists throughout conversations # and across sessions, eliminating repetition and ensuring consistency. # ================================================ # 4.1 CORE VARIABLE PRINCIPLES # ================================================ """ CRAFT Variables provide three key benefits: 1. REUSABILITY: Define once, use multiple times across different contexts 2. CONSISTENCY: Ensures all references to an entity use identical information 3. EFFICIENCY: Dramatically reduces token usage by replacing lengthy descriptions with short names """ # ================================================ # 4.2 NAMING CONVENTIONS # ================================================ # Global Constants (never change during session) PROJECT_NAME = "TaskMaster Pro" API_VERSION = "v2.5" COMPANY_NAME = "InnovateTech Solutions" # Local/Workflow Variables (temporary values) current_step = 1 user_feedback = "" session_status = "active" # Namespace Variables (organized by domain) Marketing.TARGET_AUDIENCE = "Tech-savvy professionals aged 25-45" Product.PRICING_TIERS = {"Basic": 49, "Pro": 99, "Enterprise": 249} Analytics.CONVERSION_RATE = 0.032 # Recipe System Configuration (Project-specific in PROJECT_VARIABLES) RECIPE_CONFIG = { "source_url": "https://www.aicookbook.ai/recipes-via-craft-api", "cache_enabled": True, "security_validation": True, "legacy_support": True, "version_checking": "strict" # "strict", "compatible", "any" } # ================================================ # 4.3 VARIABLE TYPES # ================================================ # Add to SESSION VARIABLES section: SESSION.ACTIVE_PERSONA = DEFAULT_CRAFT_PERSONA # Current active persona SESSION.PERSONA_PARAMETERS = {} # Current persona behavioral settings SESSION.PERSONA_HISTORY = [] # Track persona switches in session # Basic Variables COMPANY_MISSION = "To empower businesses with intelligent software solutions" MAX_RETRIES = 3 LAUNCH_DATE = "2025-07-15" # Collection Variables FEATURE_LIST = ["AI Prioritization", "Team Collaboration", "Advanced Analytics"] PRICING_STRUCTURE = { "starter": {"price": 29, "users": 5}, "professional": {"price": 79, "users": 20}, "enterprise": {"price": "custom", "users": "unlimited"} } # Computed Variables (dynamic values) def get_current_quarter(): """Returns current business quarter""" from datetime import datetime month = datetime.now().month return f"Q{(month-1)//3 + 1}" CURRENT_QUARTER = get_current_quarter() # ================================================ # 4.3.1 COMPUTED VARIABLE PATTERNS # ================================================ """ Computed variables calculate values dynamically at runtime, ensuring data freshness and reducing maintenance overhead. These patterns have been tested and verified to work reliably in CRAFT implementations. """ # Time-based Computations def get_current_date(): """ Returns formatted current date Always fresh, no manual updates needed Tested: Returns consistent format "Month DD, YYYY" """ from datetime import datetime return datetime.now().strftime("%B %d, %Y") def get_days_until(target_date): """ Calculate days until a target date Useful for deadlines, countdowns, project timelines Args: target_date: String in format "YYYY-MM-DD" Returns: Integer days until target (0 if past or invalid) Tested: Handles past dates, invalid dates, and edge cases """ try: from datetime import datetime now = datetime.now() target = datetime.strptime(target_date, "%Y-%m-%d") # Check for invalid date if isNaN(target.getTime()): return 0 diff_time = target - now diff_days = ceil(diff_time.total_seconds() / (60 * 60 * 24)) return max(0, diff_days) # Never return negative except: return 0 def get_time_since(start_date): """ Calculate elapsed time with appropriate units Automatically selects days, months, or years Args: start_date: String in format "YYYY-MM-DD" Returns: Human-readable elapsed time string Tested: Smart unit conversion, handles all edge cases """ try: from datetime import datetime start = datetime.strptime(start_date, "%Y-%m-%d") now = datetime.now() # Check for invalid date if isNaN(start.getTime()): return "Invalid date" delta = now - start days = int(delta.total_seconds() / (60 * 60 * 24)) if days < 0: return "Not started" elif days == 0: return "Today" elif days == 1: return "1 day" elif days < 30: return f"{days} days" elif days < 365: months = days // 30 return "1 month" if months == 1 else f"{months} months" else: years = days // 365 return "1 year" if years == 1 else f"{years} years" except: return "Invalid date" # Conditional Computations def get_business_hours_status(): """ Return status based on current time and business rules Tested: Correctly identifies business hours and weekends """ from datetime import datetime now = datetime.now() hour = now.hour day = now.weekday() if day >= 5: # Weekend (Saturday = 5, Sunday = 6) return "Closed - Weekend" elif hour < 9: return "Closed - Before Hours" elif hour >= 17: return "Closed - After Hours" else: return "Open" def get_current_quarter(): """ Returns current business quarter Already in spec, verified through testing """ from datetime import datetime month = datetime.now().month return f"Q{(month-1)//3 + 1}" # IMPLEMENTATION NOTES FOR AI: """ TESTED PATTERNS - These have been verified to work correctly: 1. get_current_date() - Consistent date formatting 2. get_days_until() - Countdown calculations with error handling 3. get_time_since() - Smart elapsed time with unit conversion 4. get_business_hours_status() - Conditional logic based on time 5. get_current_quarter() - Simple calculation, already in spec KEY LEARNINGS FROM TESTING: - Always validate date inputs using isNaN(date.getTime()) - Return sensible defaults for invalid inputs (0 for counts, "Invalid date" for strings) - Use max(0, value) to prevent negative day counts - Consider timezone implications for business hours """ # ================================================ # 4.4 ADVANCED VARIABLE FEATURES # ================================================ # Multi-Modal Variables (different representations of same data) PRODUCT_DESCRIPTION = { "brief": "AI-powered task management", "detailed": "TaskMaster Pro uses artificial intelligence to automatically prioritize...", "technical": "Built with React/Django, featuring ML-based task classification...", "marketing": "Never miss a deadline again with our intelligent task assistant!" } # Context-Aware Variables (adapt based on audience) def get_pitch(audience="general"): pitches = { "investor": "TaskMaster Pro has 40% MoM growth with $2M ARR...", "customer": "Save 10 hours per week with intelligent task automation...", "technical": "Our proprietary algorithm uses NLP and reinforcement learning...", "general": "TaskMaster Pro helps teams work smarter, not harder." } return pitches.get(audience, pitches["general"]) ELEVATOR_PITCH = get_pitch # Time-Sensitive Variables PROMOTIONAL_OFFER = { "code": "SUMMER2025", "discount": 0.30, "expires": "2025-08-31", "terms": "Valid for new customers only" } # ================================================ # 4.5 VARIABLE INHERITANCE # ================================================ # Base configuration that other variables can extend BASE_EMAIL_CONFIG = { "from": "team@company.com", "signature": "Best regards,\nThe Team", "footer": "© 2025 Company. All rights reserved." } # Specialized configurations inherit and extend base MARKETING_EMAIL_CONFIG = { **BASE_EMAIL_CONFIG, "from": "marketing@company.com", "tracking": True, "unsubscribe_link": True } # ================================================ # 4.6 BEST PRACTICES # ================================================ """ 1. DESCRIPTIVE NAMES: Use clear, self-documenting variable names Good: CUSTOMER_RETENTION_RATE Bad: CRR or rate1 2. CONSISTENT CASING: - UPPER_CASE for constants - lower_case for mutable variables - CamelCase for classes/types 3. NAMESPACE ORGANIZATION: Group related variables Finance.QUARTERLY_REVENUE Marketing.CAMPAIGN_ROI Product.ACTIVE_USERS 4. DOCUMENTATION: Include units and context RESPONSE_TIME = 250 # milliseconds CONVERSION_RATE = 0.035 # 3.5% 5. REGULAR REVIEW: Audit and remove unused variables periodically """ # ================================================ # 4.7 SESSION MANAGEMENT # ================================================ # Handoff variables for session continuity HANDOFF_STATE = { "last_completed_step": None, "pending_tasks": [], "session_notes": "" } # ================================================ # 4.71 VARIABLE PERSISTENCE ACROSS SESSIONS # ================================================ """ CRAFT solves the stateless nature of AI chat sessions through a simple, elegant persistence mechanism: the Project File. HOW PERSISTENCE WORKS: --------------------- 1. PROJECT FILE AS DATABASE: The PROJECT_VARIABLES section in your project file (CFT-PROJ-[number]_[name]-v[version].txt) serves as persistent storage 2. AUTOMATIC RESTORATION: When an AI assistant loads the project file at session start, all variables in PROJECT_VARIABLES are immediately available 3. TEXT-BASED SIMPLICITY: No complex serialization - just Python-compatible variable definitions that persist as plain text WHAT TO PERSIST: --------------- ✓ PERSIST THESE: - Project identifiers (names, versions, IDs) - Configuration settings that rarely change - Team information and contacts - Multi-modal content (different representations) - Project-specific constants - Complex data structures (nested dicts, lists) - Milestone tracking and status ❌ DON'T PERSIST THESE: - Function definitions (belong in Framework Spec) - Computed values (like current_date) - Class definitions - Import statements - Temporary calculations - Session-specific data EXAMPLE PROJECT_VARIABLES: ------------------------- # Project identifiers - persist across all sessions PROJECT_NAME = "CRAFT Alpha 2025" # Added: 2025-06-28 PROJECT_VERSION = "1.0.0" # Added: 2025-06-28, Update when version changes # Configuration - persistent settings PROJECT_CONFIG = { "team": { "lead": "Dr. Sarah Chen", "members": ["Alex", "Jamie", "Morgan"] }, "settings": { "notifications": True, "theme": "dark" } } # Added: 2025-06-28, Primary configuration # Multi-modal content - different views of same data PROJECT_DESCRIPTION = { "brief": "AI framework for structured chats", "detailed": "CRAFT brings OOP principles to AI interactions...", "technical": "Python-compatible framework with variables, functions..." } # Added: 2025-06-28, Context-aware descriptions PERSISTENCE VS HANDOFF: ---------------------- - PERSISTENCE: Long-term storage via PROJECT_VARIABLES (days/weeks/months) - HANDOFF: Session-to-session context via AI-CHAT-HISTORY (hours/days) Use persistence for stable project data, handoffs for work-in-progress state. BEST PRACTICES: -------------- 1. Add metadata comments with dates: # Added: YYYY-MM-DD 2. Group related variables together 3. Use clear, descriptive names 4. Document the purpose of complex structures 5. Update values by editing the project file directly TESTING PERSISTENCE: ------------------- To verify persistence is working: 1. Define a TEST_PERSISTENCE_MARKER with a counter 2. Load project in new session 3. Check counter hasn't reset 4. Increment counter 5. Future sessions should see the increment """ # Simple example - no complex configuration needed PROJECT_VARS_TO_PERSIST = { "PROJECT_NAME": "CRAFT Alpha", "VERSION": "1.0.0", "TEAM_LEAD": "Sarah Chen" } # In practice, just define variables directly in PROJECT_VARIABLES section # No special marking or configuration required - if it's there, it persists! ``` # ================================================ # 4.8 BASIC ERROR HANDLING FOR VARIABLES # ================================================ """ This section provides tested patterns for handling errors in computed variables, ensuring graceful degradation when calculations fail. """ def get_metric_safely(metric_name, default_value=0): """ Compute metric with fallback to default value Essential pattern for all computed variables that might fail Args: metric_name: Name of metric to calculate default_value: Value to return if calculation fails (any type) Returns: Calculated metric value or default if error occurs Tested: Handles missing metrics, errors, and various default types """ try: # This would be your actual metric calculation return calculate_metric(metric_name) except Exception as e: #AI->H::Caution: (Metric '{metric_name}' calculation failed: {str(e)}) #AI->H::Note: (Using default value: {default_value}) return default_value # ERROR HANDLING BEST PRACTICES (Verified through testing): """ 1. ALWAYS PROVIDE SENSIBLE DEFAULTS - Numbers: 0, -1, or domain-specific value - Strings: "N/A", "Unknown", or descriptive message - Booleans: False for safety, True for permissive - Objects: None or empty collection 2. USE CRAFT COMMENT SYSTEM FOR ERRORS - #AI->H::Caution: for computation failures - #AI->H::Note: for fallback notifications 3. SIMPLE TRY-EXCEPT IS SUFFICIENT - Don't over-engineer error handling - One level of try-except handles most cases - Return default immediately on error Example usage: revenue = get_metric_safely("revenue", default_value="N/A") user_count = get_metric_safely("active_users", default_value=0) growth_rate = get_metric_safely("growth", default_value=0.0) """ # ================================================ # 4.9 LAZY EVALUATION PATTERN # ================================================ """ The LazyVariable pattern delays expensive computations until actually needed, improving performance for complex calculations. """ class LazyVariable: """ Compute only when accessed, not at definition Tested: Caching works correctly, refresh forces recomputation Usage: expensive_data = LazyVariable(lambda: perform_complex_calculation()) # Computation happens here, only once: value = expensive_data.value # Subsequent access uses cached value: same_value = expensive_data.value # Force fresh calculation: new_value = expensive_data.refresh() """ def __init__(self, computation_func): self._func = computation_func self._computed = False self._value = None @property def value(self): """Get computed value (cached after first access)""" if not self._computed: self._value = self._func() self._computed = True return self._value def refresh(self): """Force recomputation and return new value""" self._computed = False return self.value # LAZY EVALUATION USE CASES (Verified through testing): """ 1. EXPENSIVE CALCULATIONS analytics_summary = LazyVariable(generate_full_analytics) 2. EXTERNAL DATA FETCHES api_data = LazyVariable(lambda: fetch_from_api("/endpoint")) 3. COMPLEX AGGREGATIONS yearly_report = LazyVariable(compile_annual_metrics) BENEFITS DEMONSTRATED IN TESTING: - First access: Performs computation - Subsequent accesses: Returns cached value instantly - Refresh method: Allows manual cache invalidation - Memory efficient: Only stores result, not intermediate data """ # ================================================ # 4.10 IMPLEMENTATION GUIDANCE FOR AI ASSISTANTS # ================================================ """ This section provides specific guidance for AI assistants implementing CRAFT variables, based on patterns verified through testing. """ # VARIABLE TYPE SELECTION (Based on tested patterns): """ Choose the right variable type for each use case: STATIC VALUES → Basic Variables ✓ PROJECT_NAME = "CRAFT Alpha" ✓ MAX_RETRIES = 3 ✓ API_ENDPOINT = "https://api.example.com" TIME-BASED DATA → Computed Variables ✓ CURRENT_DATE = get_current_date() ✓ DAYS_LEFT = get_days_until("2025-12-31") ✓ PROJECT_AGE = get_time_since("2025-01-01") CONDITIONAL DATA → Computed Variables with Logic ✓ OFFICE_STATUS = get_business_hours_status() ✓ CURRENT_QUARTER = get_current_quarter() ERROR-PRONE DATA → Safe Computed Variables ✓ REVENUE = get_metric_safely("revenue", "N/A") ✓ USER_COUNT = get_metric_safely("users", 0) EXPENSIVE DATA → Lazy Variables ✓ FULL_REPORT = LazyVariable(generate_complete_report) ✓ ANALYTICS = LazyVariable(compute_analytics) """ # VERIFIED BEST PRACTICES: """ 1. DATE HANDLING Always validate date strings before processing: - Check for invalid formats - Return sensible defaults (0 for counts, "Invalid date" for displays) - Use try-except around date parsing 2. ERROR HANDLING IS SIMPLE Based on testing, simple patterns work best: - Single try-except block - Clear default values - Brief error notifications via comments 3. LAZY EVALUATION GUIDELINES Use LazyVariable when: - Computation takes > 100ms - Result is not always needed - Data can become stale 4. NAMING CONVENTIONS (Reinforce standards) ✅ CORRECT: - get_current_date() - Function that computes - CURRENT_DATE - Variable storing result - LazyVariable class - PascalCase for classes ❌ AVOID: - current_date() - Missing 'get' prefix - currentDate - Not Python style - lazy_variable class - Classes need PascalCase """ # COMMON IMPLEMENTATION PATTERNS: """ When users request functionality, implement these tested patterns: "Track days until deadline" → DEADLINE = "2025-12-31" → DAYS_REMAINING = get_days_until(DEADLINE) "Show how long project has been running" → START_DATE = "2025-01-15" → PROJECT_DURATION = get_time_since(START_DATE) "Display current business status" → OFFICE_STATUS = get_business_hours_status() "Show metrics with fallbacks" → CONVERSION = get_metric_safely("conversion_rate", 0.0) "Expensive report generation" → REPORT = LazyVariable(lambda: generate_full_report()) """ # TESTING CHECKLIST FOR NEW VARIABLES: """ Before adding new computed variables, verify: □ Handles invalid inputs gracefully □ Returns appropriate default values □ Uses CRAFT comment system for errors □ Performance is acceptable (< 1 second) □ Works with handoff system □ Documented with examples """ # ================================================ # 4.11 PERSISTENCE QUICK REFERENCE # ================================================ """ CRAFT PERSISTENCE IN 30 SECONDS: 1. WHERE DO VARIABLES PERSIST? → In the PROJECT_VARIABLES section of the Project File 2. HOW DO I MAKE A VARIABLE PERSIST? → Define it in PROJECT_VARIABLES section: MY_VAR = "value" 3. WHEN ARE THEY RESTORED? → Automatically when the Project File is loaded 4. WHAT SHOULD I PERSIST? → Values, settings, configurations, project data → NOT functions, classes, or computed values 5. HOW DO I UPDATE PERSISTED VALUES? → Human edits the Project File directly 6. EXAMPLE: Project File: PROJECT_NAME = "My App" # This persists Any future session: print(PROJECT_NAME) # Output: "My App" THAT'S IT! No complex configuration needed. """ ``` # ================================================ # 5. FUNCTIONS # ================================================ # Functions in CRAFT encapsulate reusable operations, transforming complex multi-step # processes into simple, callable units that work with natural language. # ================================================ # 5.1 CORE FUNCTION PRINCIPLES # ================================================ """ CRAFT Functions provide five key benefits: 1. MODULARITY: Break complex tasks into manageable, reusable components 2. CLARITY: Self-documenting code that reads like natural language 3. EFFICIENCY: Define once, use many times with different parameters 4. CONSISTENCY: Ensure identical execution of common operations 5. COMPOSABILITY: Build complex workflows from simple building blocks """ # ================================================ # 5.11 CORE FUNCTION POLICY PRECHECK # ================================================ def policy_precheck(content, operation_type="general"): """ Automatically called by recipes before execution #H->AI::Directive: (Check content against current AI usage policies) #H->AI::Context: (Operation type: {operation_type}) Returns: - "safe": Proceed normally - "caution": Proceed with modifications - "blocked": Cannot proceed """ # ================================================ # 5.2 FUNCTION ANATOMY # ================================================ def function_name(param1, param2="default", *args, **kwargs): """ Docstring explaining purpose and usage Parameters: - param1: Description and expected type - param2: Description with default value Returns: - Description of return value and format """ #H->AI::Directive: (Core instruction for what AI should do) #H->AI::Context: (Any necessary background information) #H->AI::Structure: (Expected output format) # Function implementation return result # ================================================ # 5.3 ESSENTIAL FUNCTION PATTERNS # ================================================ # 1. CONTENT GENERATION FUNCTIONS def generate_content(topic, content_type="blog", tone="professional", word_count=500): """ Generate content based on specified parameters #H->AI::Directive: (Create {content_type} about {topic}) #H->AI::Context: (Target audience: entrepreneurs and business professionals) #H->AI::Constraint: (Maintain {tone} tone throughout) #H->AI::Structure: (Limit to approximately {word_count} words) """ return generated_content # 2. DATA TRANSFORMATION FUNCTIONS def transform_data(data, from_format, to_format, mapping=None): """ Transform data between different formats #H->AI::Directive: (Convert {data} from {from_format} to {to_format}) #H->AI::Consider: (Apply {mapping} rules if provided) #H->AI::OnError: (Return original data with error message) """ return transformed_data # 3. ANALYSIS FUNCTIONS def analyze_sentiment(text, granularity="overall", include_reasoning=False): """ Analyze emotional tone and sentiment #H->AI::Directive: (Analyze sentiment of provided text) #H->AI::Structure: (Return sentiment score, label, and reasoning if requested) #H->AI::EvaluateBy: (Consider context, tone, and word choice) """ return { "score": sentiment_score, "label": sentiment_label, "reasoning": reasoning if include_reasoning else None } # 4. WORKFLOW ORCHESTRATION FUNCTIONS def execute_workflow(workflow_name, context, checkpoints=True): """ Execute a multi-step workflow with optional checkpoints #H->AI::Directive: (Execute {workflow_name} workflow) #H->AI::Context: (Use provided context for decision making) #H->AI::Structure: (Return status updates at each checkpoint if enabled) """ workflow_results = [] for step in workflow_steps: result = execute_step(step, context) workflow_results.append(result) if checkpoints: yield {"step": step.name, "status": result.status} return workflow_results # 5. UTILITY FUNCTIONS def get_active_persona(): """Returns the currently active persona object""" return SESSION.ACTIVE_PERSONA def evaluate_persona_fit(task_description, current_persona): """Evaluates how well current persona matches the task""" # Implementation in CRAFT-PERSONA-MGR recipe pass def log_persona_switch(from_persona, to_persona, reason): """Logs persona switching for transparency""" SESSION.PERSONA_HISTORY.append({ "timestamp": get_timestamp(), "from": from_persona.id, "to": to_persona.id, "reason": reason }) # ================================================ # 5.4 FUNCTION COMPOSITION # ================================================ # Functions can be combined to create complex operations def create_and_analyze_content(topic, audience): """ Generate content and analyze its effectiveness """ # Generate initial content content = generate_content(topic, tone="conversational") # Analyze sentiment sentiment = analyze_sentiment(content) # Adjust if needed if sentiment["score"] < 0.6: content = generate_content(topic, tone="enthusiastic") # Create final package return { "content": content, "analysis": sentiment, "audience_fit": analyze_audience_fit(content, audience) } # ================================================ # 5.5 PARAMETERIZED FUNCTIONS # ================================================ # Functions can accept complex parameters for flexibility def build_campaign(campaign_config): """ Build complete marketing campaign from configuration Parameters: - campaign_config: Dictionary containing: - name: Campaign identifier - goals: List of objectives - audience: Target persona - channels: List of marketing channels - budget: Available budget """ #H->AI::Directive: (Create comprehensive campaign plan) #H->AI::Context: (Optimize for ROI within budget constraints) #H->AI::Structure: (Include timeline, content calendar, and KPIs) return campaign_plan # ================================================ # 5.6 ERROR HANDLING PATTERNS # ================================================ def safe_operation(operation, fallback_value=None, max_retries=3): """ Execute operation with automatic retry and fallback """ #H->AI::Directive: (Attempt {operation} with error handling) #H->AI::OnError: (Retry up to {max_retries} times, then use {fallback_value}) for attempt in range(max_retries): try: result = operation() return result except Exception as e: if attempt == max_retries - 1: return fallback_value continue # ================================================ # 5.7 ASYNC AND STREAMING FUNCTIONS # ================================================ async def generate_report_async(data_source, report_type): """ Generate report asynchronously with progress updates #H->AI::Directive: (Generate {report_type} report from {data_source}) #H->AI::Structure: (Stream progress updates as sections complete) """ sections = ["summary", "analysis", "recommendations", "appendix"] for section in sections: content = await generate_section(section, data_source) yield { "section": section, "content": content, "progress": f"{sections.index(section)+1}/{len(sections)}" } # ================================================ # 5.8 FUNCTION DECORATORS # ================================================ # Decorators add common functionality to functions @log_execution @validate_inputs @cache_results(ttl=3600) def expensive_analysis(dataset): """ Perform computationally expensive analysis with caching """ #H->AI::Directive: (Perform deep analysis on dataset) #H->AI::Context: (This may take several steps) return analysis_results # ================================================ # 5.9 RECIPE FUNCTIONS # ================================================ # Recipe collection for caching RECIPE_COLLECTION = {} def fetch_recipe(recipe_url, options=None): """ Framework-standard recipe fetching function Maintains compatibility with fetch_recipe_from_aicookbook() #H->AI::Directive: (Fetch and validate recipe from configured source) #H->AI::Context: (Use web_fetch with error recovery) #H->AI::OnError: (Apply 4-level fallback strategy) Options: - max_retries: Number of retry attempts (default: 3) - use_cache: Whether to check cache first (default: True) - fallback_mode: How to handle failures (default: "auto") Example: recipe = fetch_recipe( "https://www.aicookbook.ai/recipes-via-craft-api/rcp-001", options={"max_retries": 5, "use_cache": True} ) """ options = options or {} # Validate URL format if not validate_url_format(recipe_url): return create_error_response( "ValidationError", "Invalid recipe URL format", {"url": recipe_url}, "Ensure URL follows the correct format", False ) # Check cache first if enabled if options.get("use_cache", RECIPE_ERROR_CONFIG.get("enable_caching", True)): cached_recipe = RECIPE_COLLECTION.get(recipe_url) if cached_recipe: #AI->H::Note: (Using cached recipe for {recipe_url}) return { "status": "cached", "recipe": cached_recipe, "message": "Recipe loaded from cache" } # Attempt fetch with retries max_retries = options.get("max_retries", RECIPE_ERROR_CONFIG["max_retry_attempts"]) for attempt in range(max_retries): try: #H->AI::Directive: (Use web_fetch to retrieve the recipe page) #AI->H::Status: (Fetching recipe from {recipe_url}, attempt {attempt + 1}/{max_retries}) # In actual implementation, this would use web_fetch # page_content = web_fetch(recipe_url) # For framework spec, we'll provide the structure page_content = None # Replace with actual web_fetch if page_content: # Parse the recipe parsed_result = parse_recipe_safe(page_content, recipe_url) if parsed_result.get("status") == "success": # Cache successful fetch recipe = parsed_result["recipe"] RECIPE_COLLECTION[recipe_url] = recipe return { "status": "success", "recipe": recipe, "message": "Recipe successfully fetched and parsed" } else: # Parsing failed, try fallback return apply_fallback_strategy(recipe_url, parsed_result, options) except Exception as e: if attempt < max_retries - 1: # Exponential backoff if RECIPE_ERROR_CONFIG.get("exponential_backoff", True): wait_time = RECIPE_ERROR_CONFIG["backoff_base"] ** attempt #AI->H::Status: (Network error on attempt {attempt + 1}, retrying in {wait_time} seconds) else: # All retries exhausted return handle_network_failure(recipe_url, str(e), options) # Should not reach here, but just in case return create_error_response( "NetworkError", "Failed to fetch recipe after all retries", {"url": recipe_url, "attempts": max_retries}, "Try again later or use a cached recipe", True ) def quick_recipe(recipe_url, **parameters): """ Framework-standard quick execution Backward compatible with existing usage #H->AI::Directive: (Fetch and execute recipe in one call) #H->AI::Context: (Validate parameters before execution) Example: result = quick_recipe( "https://www.aicookbook.ai/recipes-via-craft-api/email-subject", topic="AI automation", count=5 ) """ # Fetch recipe with error handling fetch_result = fetch_recipe(recipe_url) # Handle fetch errors if fetch_result.get("status") == "error": error_message = format_error_for_user(fetch_result) #AI->H::Caution: (Recipe fetch failed: {error_message}) return fetch_result # Get recipe (might be cached or fallback) recipe = fetch_result.get("recipe") if not recipe: return create_error_response( "ExecutionError", "No recipe available for execution", {"fetch_result": fetch_result}, "Verify recipe URL and retry", True ) # Execute with parameter validation execution_result = execute_recipe_safe(recipe, parameters) # Add metadata about source execution_result["recipe_source"] = fetch_result.get("status", "unknown") if fetch_result.get("warning"): execution_result["source_warning"] = fetch_result["warning"] return execution_result def execute_recipe_safe(recipe, user_inputs): """ Execute recipe with comprehensive parameter validation #H->AI::Directive: (Validate all parameters before execution) """ # Validate parameters validation_result = validate_recipe_parameters(recipe, user_inputs) if validation_result.get("status") == "error": return validation_result # Apply any parameter conversions processed_inputs = process_parameters(recipe, user_inputs) try: # Execute the recipe result = recipe.execute(processed_inputs) # Add any warnings from validation if validation_result.get("warnings"): result["warnings"] = validation_result["warnings"] return result except Exception as e: return create_error_response( "ExecutionError", f"Recipe execution failed: {str(e)}", { "recipe_id": recipe.recipe_id, "error_type": type(e).__name__ }, "Check parameters and try again", True ) def validate_recipe_parameters(recipe, user_inputs): """ Validate parameters before execution with security checks #H->AI::Directive: (Check all parameters meet requirements and security policies) #H->AI::Context: (Block potentially harmful content) """ # Security check for injection attempts forbidden_patterns = ["H::SecurityWarning: (Potentially unsafe content detected in parameters) return { "status": "error", "error_type": "SecurityError", "message": "Security violation in parameter content" } # Check required parameters for param_name, param_config in recipe.parameters.items(): if param_config.get("required", False) and param_name not in user_inputs: return { "status": "error", "error_type": "ValidationError", "message": f"Missing required parameter: {param_name}" } # Validate parameter types for param_name, param_value in user_inputs.items(): if param_name in recipe.parameters: expected_type = recipe.parameters[param_name].get("type") if expected_type == "integer" and not isinstance(param_value, int): return { "status": "error", "error_type": "ValidationError", "message": f"Parameter {param_name} must be an integer" } return {"status": "success"} # ================================================ # 5.10 BEST PRACTICES # ================================================ """ 1. SINGLE RESPONSIBILITY: Each function should do one thing well 2. DESCRIPTIVE NAMES: Use verb_noun pattern (generate_report, analyze_data) 3. PARAMETER VALIDATION: Check inputs early and fail gracefully 4. DOCUMENTATION: Always include docstrings with examples 5. COMPOSABILITY: Design functions to work well together 6. IDEMPOTENCY: Same inputs should produce same outputs 7. TOKEN EFFICIENCY: Minimize internal prompt complexity Example of well-structured function: def summarize_document(document, max_words=100, style="executive"): ''' Create concise summary of document Examples: >>> summarize_document(annual_report, max_words=200, style="technical") >>> summarize_document(blog_post, style="casual") ''' #H->AI::Directive: (Summarize the document in {style} style) #H->AI::Constraint: (Limit to {max_words} words maximum) #H->AI::Focus: (Capture key points and actionable insights) return summary """ # ================================================ # 6. OBJECTS # ================================================ # Objects in CRAFT bundle related data and behaviors into cohesive units, # bringing object-oriented design principles to AI conversations. # ================================================ # 6.1 CORE OBJECT PRINCIPLES # ================================================ """ CRAFT Objects provide six key benefits: 1. MODULARITY: Define once, reuse everywhere as self-contained units 2. CLARITY: Replace ambiguous instructions with explicit, structured objects 3. SCALABILITY: Maintain state across sessions for complex, long-term projects 4. TOKEN EFFICIENCY: Reduce 50+ token instructions to 5-10 token object calls 5. BUSINESS ALIGNMENT: Encode rules and compliance directly into reusable objects 6. COLLABORATION: Provide common vocabulary for teams working with AI """ # ================================================ # 6.2 OBJECT CATEGORIES # ================================================ # 1. CONTENT-ORIENTED OBJECTS class Prompt: """Template with variables for reusable prompts""" def __init__(self, template, variables, default_format="text"): self.template = template self.variables = variables self.default_format = default_format def fill(self, **kwargs): #H->AI::Directive: (Fill template with provided values) return self.template.format(**kwargs) class AIRecipe: """Tested sequence of prompts for specific tasks""" def __init__(self, name, steps, expected_outcome): self.name = name self.steps = steps self.expected_outcome = expected_outcome def execute(self, context=None): #H->AI::Directive: (Execute recipe steps in sequence) return results # 2. WORKFLOW & DECISION OBJECTS class Workflow: """Multi-step process with automatic progression""" def __init__(self, name, steps, checkpoints=True): self.name = name self.steps = steps self.checkpoints = checkpoints self.current_step = 0 def next(self): #H->AI::Directive: (Execute next step in workflow) if self.current_step < len(self.steps): result = self.steps[self.current_step].execute() self.current_step += 1 return result class AIDecisionPoint: """Conditional branching based on metrics or conditions""" def __init__(self, trigger, condition, if_true, if_false): self.trigger = trigger self.condition = condition self.if_true = if_true self.if_false = if_false def evaluate(self): #H->AI::Directive: (Evaluate condition and execute appropriate branch) if eval(self.condition): return self.if_true.execute() return self.if_false.execute() # 3. KNOWLEDGE & RELATIONSHIP OBJECTS class KnowledgeGraphNode: """Entity with properties and relationships""" def __init__(self, id, type, properties, relationships=None): self.id = id self.type = type self.properties = properties self.relationships = relationships or [] def add_relationship(self, predicate, target): #H->AI::Context: (Track relationship in knowledge graph) self.relationships.append((predicate, target)) # 4. VALIDATION & FORMATTING OBJECTS class ConstraintSet: """Reusable rules for content generation""" def __init__(self, name, rules): self.name = name self.rules = rules def apply(self, content): #H->AI::Directive: (Validate and adjust content per rules) #H->AI::Constraint: (Enforce all rules: {self.rules}) return validated_content class OutputSchema: """Structured format requirements for AI responses""" def __init__(self, name, fields, format="json"): self.name = name self.fields = fields self.format = format def validate(self, output): #H->AI::Directive: (Ensure output matches schema) return is_valid # 5. DYNAMIC PERSONA OBJECTS class AIPersona: """Switchable AI personality/expertise modes""" def __init__(self, name, expertise, tone, constraints=None): self.name = name self.expertise = expertise self.tone = tone self.constraints = constraints or [] def activate(self): #H->AI::Role: (Assume persona: {self.name}) #H->AI::Context: (Expertise: {self.expertise}, Tone: {self.tone}) return f"Persona '{self.name}' activated" # ================================================ # 6.3 ADVANCED OBJECT PATTERNS # ================================================ # GENERATOR OBJECTS class ContentCampaign: """Content factory for coordinated multi-channel campaigns""" def __init__(self, name, topic, audience, tone, keywords): self.name = name self.topic = topic self.audience = audience self.tone = tone self.keywords = keywords def generate_blog_titles(self, count=5): #H->AI::Directive: (Generate {count} blog titles about {self.topic}) #H->AI::Context: (Audience: {self.audience}, Tone: {self.tone}) return titles def draft_social_post(self, platform): #H->AI::Directive: (Create {platform} post conveying core message) return post # STATEFUL PROJECT OBJECTS class ProjectTracker: """Maintains project state across sessions""" def __init__(self, name, budget=0, status="Planning"): self.name = name self.status = status self.budget = budget self.milestones = {} self.key_decisions = [] self.hours_logged = 0.0 def add_milestone(self, name, due_date): self.milestones[name] = {"status": "Not Started", "due_date": due_date} def generate_report(self): #H->AI::Directive: (Generate project status report) return report # INTERACTIVE OBJECTS class AB_Test: """Guided A/B testing workflow""" def __init__(self, name, hypothesis, goal): self.name = name self.hypothesis = hypothesis self.goal = goal self.variants = {} self.status = "Defining" #AI->H::Note: (AB_Test '{name}' created. Add variants using .add_variant()) def add_variant(self, name, description): self.variants[name] = {"description": description} if "control" in self.variants and len(self.variants) > 1: #AI->H::RecommendedChange: (Ready to start test with .start_test()) # ================================================ # 6.4 OBJECT COMPOSITION # ================================================ # Objects can contain other objects for sophisticated hierarchies class BusinessPlan: """Composite object containing multiple components""" def __init__(self, name): self.name = name self.market_analysis = MarketAnalysis() self.financial_projections = FinancialModel() self.marketing_strategy = ContentCampaign() self.team_structure = TeamOrganization() def generate_executive_summary(self): #H->AI::Directive: (Synthesize summary from all components) return summary # ================================================ # 6.5 PRACTICAL IMPLEMENTATION GUIDE # ================================================ """ STEP 1: IDENTIFY PATTERNS Look for repeated instructions or complex tasks: - "Analyze financial data..." → FinancialAnalyzer object - "Compare vendor offerings..." → VendorComparison object - "Generate weekly report..." → ReportGenerator object STEP 2: DESIGN DATA MODEL Define attributes and behaviors: class CustomerAnalysis: def __init__(self, segment, metrics, timeframe): self.segment = segment # "enterprise", "SMB", etc. self.metrics = metrics # ["churn", "LTV", "NPS"] self.timeframe = timeframe # "Q1-2025" STEP 3: EMBED IN SPEC Add to your CRAFT specification with examples: # Usage: analyzer = CustomerAnalysis("enterprise", ["churn", "LTV"], "Q1-2025") STEP 4: DOCUMENT BEHAVIOR Specify AI interpretation: - Parse customer data for specified segment - Calculate requested metrics - Generate insights and recommendations STEP 5: TEST & ITERATE Verify consistent behavior across sessions """ # ================================================ # 6.6 BEST PRACTICES # ================================================ """ 1. SINGLE RESPONSIBILITY: Each object should represent one concept 2. CLEAR INTERFACES: Methods should have obvious purposes 3. STATE MANAGEMENT: Track what changes between calls 4. INHERITANCE: Use base objects for common patterns 5. COMPOSITION: Combine simple objects for complex behaviors Example of well-designed object: class EmailCampaign: '''Manages email marketing campaigns''' def __init__(self, name, audience, goal): self.name = name self.audience = audience # Persona object self.goal = goal # Metric object self.emails = [] self.status = "draft" def add_email(self, subject, template): '''Add email to campaign sequence''' self.emails.append({"subject": subject, "template": template}) def validate(self): '''Ensure campaign meets requirements''' #H->AI::Directive: (Check campaign completeness) return validation_results """ # ================================================ # 7. CRAFT RECIPE SYSTEM (New in v0.0625b1) # ================================================ # The CRAFT Recipe System extends the framework to support parameterized, # reusable prompt templates that can be fetched and executed dynamically. # ================================================ # 7.1 CORE RECIPE PRINCIPLES # ================================================ """ CRAFT Recipes extend the framework's core philosophy by treating prompts as reusable, parameterized objects. They provide: 1. PROMPT REUSABILITY: Define once, use everywhere with different parameters 2. VERSION CONTROL: Track prompt evolution and ensure compatibility 3. STRUCTURED DISCOVERY: Organized categories for finding the right recipe 4. SEAMLESS INTEGRATION: Recipes can use all CRAFT components (Variables, Functions, Objects) 5. SECURITY BY DESIGN: Validated inputs and sandboxed execution 6. TOKEN OPTIMIZATION: Parameterized templates reduce repetitive token usage Recipes transform ad-hoc prompting into a structured, efficient process that maintains consistency while allowing flexibility through parameters. """ # ================================================ # 7.11 RECIPE IDENTIFICATION SYSTEM # ================================================ COM_EXTENSION_PATTERN = { "naming": "COM-EXT-CAT{XXX}-v{version}", "location": "First recipe in each specialized cookbook", "purpose": "Cookbook-specific recipe detection logic", "integration": "Automatically called by CRAFT-OPERATIONS-MANAGER" } # ================================================ # 7.2 RECIPE IDENTIFICATION SYSTEM # ================================================ RECIPE_ID_FORMAT = { "pattern": "RCP-[XXX]-[YYY]-[ZZZ]-[NAME]-v[MAJOR].[MINOR][PATCH]", "components": { "prefix": "RCP", "category_group": "XXX", # 001-999: Flexible category grouping "subcategory": "YYY", # 001-999: Flexible subcategory "sequence": "ZZZ", # 001-999: Sequence within subcategory "name": "NAME", # Descriptive name (alphanumeric + hyphens) "version": { "major": "1-999", # Breaking changes "minor": "00-99", # New features, backward compatible "patch": "a-z" # Bug fixes, minor updates } }, "flexibility": { "category_ranges": "Categories can use any range from 001-999", "subcategory_ranges": "Subcategories can use any range from 001-999", "sequence_ranges": "Sequences must start at 001 and increment", "organizational_freedom": "Projects can organize their numbering as needed" }, "legacy_support": True, # Support old format RCP-001-ULTRA-PROMPT "examples": [ "RCP-001-001-001-EMAIL-SUBJECT-v1.00a", # Valid - foundational recipe "RCP-101-001-001-BLOG-TITLE-v1.00a", # Valid - content category "RCP-999-999-999-ADVANCED-AI-v2.15c", # Valid - experimental "RCP-001-ULTRA-PROMPT" # Legacy format still supported ] } # SECURITY CROSS-VERIFICATION SYSTEM SECURITY_VERIFICATION_CHECKSUM = { "framework_spec": { "section_1_10": "Recipe Security Validation Protocol", "section_2_3": "SecurityWarning comment type", "section_7_9": "validate_recipe_parameters function" }, "cookbook_file": { "security_protocol": "RECIPE SECURITY REQUIREMENTS", "chat_init_check": "SECURITY VERIFICATION step" } } def verify_security_layers(): """ Verify all security layers are present across files #H->AI::Directive: (Cross-check security implementation) #H->AI::Context: (Part of multi-file security verification) """ layers_present = [] # Check Framework Spec components if has_section("1.10") and has_comment_type("SecurityWarning"): layers_present.append("framework_security") # Check Cookbook components if cookbook_has_security_protocol(): layers_present.append("cookbook_security") # Check Recipe validation if function_exists("validate_recipe_parameters"): layers_present.append("parameter_security") if len(layers_present) < 3: #AI->H::Caution: (Security layers incomplete - some protections may be missing) return False RECIPE_SECURITY_VERIFICATION = { "self_check": True, "verify_framework_integrity": True, "required_components": [ "Section 1.10 exists in Framework Specification", "SecurityWarning comment type defined", "Recipe source validation active" ] } def verify_security_active(): """ Recipes can verify security is active #H->AI::Directive: (Check framework security components exist) #H->AI::Context: (Part of recipe self-protection) """ # Check for Section 1.10 if not framework_has_section("1.10"): #AI->H::Caution: (Framework security may be compromised) return False # Verify comment type exists if "SecurityWarning" not in available_comment_types(): #AI->H::Caution: (Security communication protocol missing) return False return True RECIPE_CATEGORY_ORGANIZATION = { "numbering_system": "sequential", "category_reservation": { "001-050": "Reserved for CRAFT Cookbook files", "051-999": "Reserved for AICookbook.ai website organization", "policy": "Cookbook files MUST use categories 001-050 only", "rationale": "Provides clear separation between local cookbook organization and website taxonomy" }, "current_cookbook_categories": { "001": "CORE - Essential CRAFT framework recipes", "002": "CONTENT-AND-PROMO - Content creation and promotional recipes", "003": "BUSINESS - Business documentation and analysis recipes", "004": "CYBERSECURITY - Security assessment and documentation recipes", "005-050": "Reserved for future cookbook files" }, "website_categories": { "051+": "Categories defined and managed at AICookbook.ai", "note": "Website categories may include subcategories and hierarchical organization" } } # URL Structure Configuration RECIPE_URL_CONFIG = { "base_url": "https://www.aicookbook.ai/recipes-via-craft-api", # Override in PROJECT_VARIABLES "category_prefix": "CAT-", "subcategory_prefix": "SUBCAT-", "recipe_prefix": "rcp-", "paths": { "category_listing": "/list-all-categories", "category": "/category/{category_id}", "subcategory": "/tag/{subcategory_id}", "recipe": "/{recipe_id}" } } # Error Handling Configuration RECIPE_ERROR_CONFIG = { "max_retry_attempts": 3, "default_timeout": 30, # seconds "enable_caching": True, "enable_error_logging": True, "exponential_backoff": True, "backoff_base": 2 # seconds } # ================================================ # 7.3 CORE ERROR HANDLING # ================================================ # Global error tracking (initialize in project if needed) RECIPE_ERROR_LOG = [] def create_error_response(error_type, message, details=None, fallback=None, retry_possible=False): """ Create standardized error response #H->AI::Directive: (Generate consistent error format) Parameters: error_type: One of NetworkError, ParseError, ValidationError, ExecutionError, SecurityError message: Human-readable error message details: Dict with additional error context fallback: Suggested action for recovery retry_possible: Whether the operation can be retried Returns: Dict with standardized error structure """ from datetime import datetime error_response = { "status": "error", "error_type": error_type, "message": message, "timestamp": datetime.now().isoformat(), "details": details or {}, "fallback": fallback or "Check documentation or retry later", "retry_possible": retry_possible } # Log error if logging enabled if RECIPE_ERROR_CONFIG.get("enable_error_logging", True): log_error(error_response) return error_response def log_error(error_response): """ Track errors for debugging and pattern analysis #H->AI::Context: (Store errors for system health monitoring) """ RECIPE_ERROR_LOG.append({ "timestamp": error_response.get("timestamp"), "error": error_response, "session_id": "CRAFT-SESSION" }) # Check for repeated errors recent_errors = [e for e in RECIPE_ERROR_LOG[-10:] if e["error"]["error_type"] == error_response["error_type"]] if len(recent_errors) > 5: #AI->H::Caution: (Multiple {error_response["error_type"]} errors detected - system may need attention) def format_error_for_user(error_response): """ Convert technical errors to user-friendly messages #H->AI::Directive: (Make errors actionable and clear) """ templates = { "NetworkError": "📡 Connection issue: {message}\n💡 Try: {fallback}", "ParseError": "📄 Recipe format issue: {message}\n💡 Fix: {fallback}", "ValidationError": "✏️ Parameter issue: {message}\n💡 Update: {fallback}", "ExecutionError": "⚙️ Execution issue: {message}\n💡 Alternative: {fallback}", "SecurityError": "🔒 Security issue: {message}\n💡 Action: {fallback}" } error_type = error_response.get("error_type", "Unknown") template = templates.get(error_type, "Error: {message}") return template.format( message=error_response.get("message", "Unknown error"), fallback=error_response.get("fallback", "Contact support") ) # ================================================ # 7.4 RECIPE OBJECT CLASS # ================================================ class CRAFTRecipe: """ Core recipe object that reads from AICookbook.ai webpages Extensible design for future enhancements """ def __init__(self, recipe_source): """ Initialize from various sources: - URL string: "https://www.aicookbook.ai/recipes-via-craft-api/..." - Recipe data dict: {"recipe_id": ..., "title": ..., ...} - Legacy format support """ self.recipe_id = None self.version = None self.legacy_mode = False # Parse recipe based on source type if isinstance(recipe_source, str) and recipe_source.startswith("http"): self._load_from_url(recipe_source) elif isinstance(recipe_source, dict): self._load_from_dict(recipe_source) # Check for legacy ID format if self.recipe_id and not re.match(r"RCP-\d{3}-\d{3}-\d{3}-", self.recipe_id): self.legacy_mode = True #AI->H::Note: (Using legacy recipe format for {self.recipe_id}) def _load_from_url(self, url): """Load recipe from AICookbook.ai URL""" #H->AI::Directive: (Fetch and parse recipe from {url}) #H->AI::Context: (Use web_fetch with structured text parsing) #H->AI::OnError: (Apply fallback strategies) # SECURITY: Validate URL before fetch if not url.startswith("https://www.aicookbook.ai/recipes-via-craft-api/"): #AI->H::SecurityWarning: (Invalid recipe source) raise SecurityError("Unauthorized recipe source") # After fetching, validate content # Check for required markers if "CRAFT RECIPE START" not in content: #AI->H::SecurityWarning: (Invalid recipe format - missing start marker) raise SecurityError("Invalid recipe format") def _load_from_dict(self, recipe_data): """Load recipe from dictionary data""" self.recipe_id = recipe_data.get("recipe_id", "unknown") self.title = recipe_data.get("title", "Untitled Recipe") self.description = recipe_data.get("description", "") self.difficulty = recipe_data.get("difficulty", "easy") self.prompt_template = recipe_data.get("prompt_template", "") self.parameters = recipe_data.get("parameters", {}) self.examples = recipe_data.get("examples", []) self.version = self._parse_version(self.recipe_id) def _parse_version(self, recipe_id): """Extract version from recipe ID""" if "-v" in recipe_id: base_id, version_str = recipe_id.rsplit("-v", 1) return self._parse_version_string(version_str) return {"major": 1, "minor": 0, "patch": "a"} # Default version def validate_compatibility(self, craft_version=None): """Check if recipe is compatible with current CRAFT version""" if not hasattr(self, 'compatibility'): return True # No compatibility constraints return self._check_version_compatibility(craft_version) def can_use_component(self, component_type, component_name): """Check if recipe can access a CRAFT component""" # Recipes have full access to CRAFT components return True def execute(self, user_inputs): """Execute recipe with parameter validation""" #H->AI::Directive: (Execute recipe with provided parameters) #H->AI::Context: (Validate parameters and apply template) #H->AI::OnError: (Return detailed error information) # Validate parameters validation_result = self.validate_parameters(user_inputs) if validation_result.get("status") == "error": return validation_result # Execute template try: filled_prompt = self.prompt_template.format(**user_inputs) return { "status": "success", "prompt": filled_prompt, "recipe_id": self.recipe_id, "parameters_used": list(user_inputs.keys()) } except Exception as e: return { "status": "error", "error_type": "ExecutionError", "message": str(e) } def validate_parameters(self, user_inputs): """Validate parameters before execution""" #H->AI::Directive: (Check all parameters meet requirements) # Implementation in project file def get_info(self): """Get recipe information""" return { "recipe_id": self.recipe_id, "title": self.title, "description": self.description, "difficulty": self.difficulty, "parameters": self.parameters, "version": self.version, "legacy_mode": self.legacy_mode } # ================================================ # 7.5 RECIPE DISCOVERY AND ORGANIZATION # ================================================ RECIPE_ORGANIZATION = { "base_url": "https://www.aicookbook.ai/recipes-via-craft-api", "categories": { "pattern": "CAT-[NAME]", "url_pattern": "/category/{category_id}", "examples": ["CAT-Content", "CAT-Marketing", "CAT-Technical"] }, "subcategories": { "pattern": "SUBCAT-[NAME]", "url_pattern": "/tag/{subcategory_id}", "examples": ["SUBCAT-Email", "SUBCAT-Blog", "SUBCAT-Analysis"] }, "listing_url": "/list-all-categories", "hierarchy": { "enabled": True, "max_depth": 3, "structure": "category/subcategory/recipe" } } def discover_recipes(filter_criteria=None): """ Discover available recipes with optional filtering #H->AI::Directive: (Fetch and parse recipe listings) #H->AI::Context: (Use category system for organization) Parameters: filter_criteria: dict with optional keys: - category: Filter by category (e.g., "CAT-Content") - subcategory: Filter by subcategory (e.g., "SUBCAT-Email") - difficulty: Filter by difficulty level - version: Minimum version requirement Returns: List of recipe summaries matching criteria """ # Implementation fetches from listing URL and filters category_listing = fetch_category_listing() recipes = [] if filter_criteria: # Apply filters if "category" in filter_criteria: recipes = filter_by_category(recipes, filter_criteria["category"]) if "subcategory" in filter_criteria: recipes = filter_by_subcategory(recipes, filter_criteria["subcategory"]) return recipes def list_categories(): """ List all available recipe categories #H->AI::Directive: (Fetch category listing from recipe source) #H->AI::Context: (Parse plaintext listing format) Returns: List of category dictionaries with id, name, and recipe count """ listing_url = get_category_listing_url() #H->AI::Directive: (Use web_fetch to retrieve {listing_url}) # Parse category listing format categories = [] # Implementation specific to source format return categories def list_subcategories(category_id=None): """ List subcategories, optionally filtered by category #H->AI::Directive: (Extract subcategory list from listings) Parameters: category_id: Optional category filter (e.g., "CAT-Content") Returns: List of subcategory dictionaries """ all_subcategories = [] if category_id: # Filter to specific category #H->AI::Context: (Filter subcategories belonging to {category_id}) return all_subcategories def list_recipes_in_category(category_id): """ List all recipes in a specific category #H->AI::Directive: (Fetch recipes for {category_id}) Parameters: category_id: Category identifier (e.g., "CAT-Content") Returns: List of recipe summaries in the category """ category_url = get_category_url(category_id) #H->AI::Directive: (Fetch and parse recipes from {category_url}) recipes = [] # Parse category page for recipe links return recipes def list_recipes_in_subcategory(subcategory_id): """ List all recipes in a specific subcategory Parameters: subcategory_id: Subcategory identifier (e.g., "SUBCAT-Email") Returns: List of recipe summaries in the subcategory """ subcategory_url = get_subcategory_url(subcategory_id) recipes = [] # Implementation return recipes def search_recipes_by_keyword(keyword): """ Search recipes by keyword in title or description Parameters: keyword: Search term Returns: List of matching recipe summaries """ all_recipes = discover_recipes() matches = [] for recipe in all_recipes: if keyword.lower() in recipe.get("title", "").lower() or \ keyword.lower() in recipe.get("description", "").lower(): matches.append(recipe) return matches # URL Builder Functions def get_category_listing_url(): """Get URL for category listing page""" base = RECIPE_URL_CONFIG.get("base_url", RECIPE_ORGANIZATION["base_url"]) path = RECIPE_URL_CONFIG["paths"]["category_listing"] return f"{base}{path}" def get_category_url(category_id): """Build URL for specific category""" base = RECIPE_URL_CONFIG.get("base_url", RECIPE_ORGANIZATION["base_url"]) path = RECIPE_URL_CONFIG["paths"]["category"].format(category_id=category_id) return f"{base}{path}" def get_subcategory_url(subcategory_id): """Build URL for specific subcategory""" base = RECIPE_URL_CONFIG.get("base_url", RECIPE_ORGANIZATION["base_url"]) path = RECIPE_URL_CONFIG["paths"]["subcategory"].format(subcategory_id=subcategory_id) return f"{base}{path}" def get_recipe_url(recipe_id): """Build URL for specific recipe""" base = RECIPE_URL_CONFIG.get("base_url", RECIPE_ORGANIZATION["base_url"]) path = RECIPE_URL_CONFIG["paths"]["recipe"].format(recipe_id=recipe_id) return f"{base}{path}" # Validation Functions def validate_category_id(category_id): """Validate category ID format""" import re pattern = r"^CAT-[A-Za-z][A-Za-z0-9-]*$" return bool(re.match(pattern, category_id)) def validate_subcategory_id(subcategory_id): """Validate subcategory ID format""" import re pattern = r"^SUBCAT-[A-Za-z][A-Za-z0-9-]*$" return bool(re.match(pattern, subcategory_id)) def validate_recipe_id(recipe_id): """Validate recipe ID format (supports both new and legacy)""" import re # New format - accepting 001-999 for all numeric components new_pattern = r"^RCP-(\d{3})-(\d{3})-(\d{3})-[A-Z0-9-]+-v\d+\.\d{2}[a-z]$" # Legacy format legacy_pattern = r"^RCP-\d{3}-[A-Z0-9-]+$" # URL format url_pattern = r"^rcp-\d{3}-[a-z0-9-]+$" match = re.match(new_pattern, recipe_id) if match: # Validate numeric ranges (001-999) cat, subcat, seq = int(match.group(1)), int(match.group(2)), int(match.group(3)) if 1 <= cat <= 999 and 1 <= subcat <= 999 and 1 <= seq <= 999: return True return bool(re.match(legacy_pattern, recipe_id) or re.match(url_pattern, recipe_id)) def fetch_category_listing(): """ Fetch and parse the category listing #H->AI::Directive: (Retrieve category listing and parse structure) Expected format: # CRAFT Recipe Categories ## Categories ### CAT-Foundational Basic recipes for common tasks ### CAT-Content Content generation recipes - SUBCAT-Email - SUBCAT-Blog Returns: Dict with categories and their subcategories """ url = get_category_listing_url() # Fetch and parse implementation return {} # ================================================ # 7.6 VERSION MANAGEMENT # ================================================ # NOTE: This section covers recipe-specific version management # (comparing recipe versions, checking compatibility, migration paths). # For the full CRAFT Versioning System (file versioning, manifests, # changelogs, distribution, update mechanism), see Section 12. # ================================================ class RecipeVersionManager: """ Handles recipe versioning and migration """ def compare_versions(self, v1, v2): """ Compare two recipe versions Returns: -1 if v1 < v2, 0 if equal, 1 if v1 > v2 """ # Compare major.minor.patch def check_compatibility(self, recipe_version, required_version): """Check if recipe version meets requirements""" # Semantic versioning rules def get_migration_path(self, from_version, to_version): """ Determine migration steps between versions Returns list of migration functions to apply """ migrations = [] # Build migration path return migrations def migrate_parameters(self, old_params, from_version, to_version): """Migrate parameters between recipe versions""" # Apply migrations in sequence # ================================================ # 7.7 SECURITY FRAMEWORK # ================================================ RECIPE_SECURITY_POLICIES = { "parameter_validation": { "max_string_length": 10000, "forbidden_patterns": ["AI::Directive: (Execute fallback hierarchy based on configuration) Parameters: recipe_url: Original recipe URL that failed error_result: Error details from the failure options: Additional options for fallback behavior Returns: Fallback result or error if no fallback available """ options = options or {} fallback_mode = options.get("fallback_mode", "auto") if fallback_mode == "none": return error_result # Try each fallback level for level in RECIPE_ERROR_HANDLING["fallback_levels"]: if level["name"] == "cached_version": cached = RECIPE_COLLECTION.get(recipe_url) if cached: return { "status": "fallback", "recipe": cached, "warning": f"Using cached version due to: {error_result.get('message')}", "fallback_level": level["name"] } elif level["name"] == "embedded_default": recipe_type = guess_recipe_type(recipe_url) if recipe_type in EMBEDDED_FALLBACK_RECIPES: fallback_recipe = CRAFTRecipe(EMBEDDED_FALLBACK_RECIPES[recipe_type]) return { "status": "fallback", "recipe": fallback_recipe, "warning": f"Using embedded {recipe_type} template", "fallback_level": level["name"] } elif level["name"] == "generic_template": # Could implement generic templates by category category = extract_category_from_url(recipe_url) if category and has_generic_template(category): return create_generic_template_response(category) elif level["name"] == "manual_mode": return { "status": "manual", "instructions": get_manual_instructions(recipe_url, error_result), "original_error": error_result } # No fallback worked return error_result def handle_network_failure(recipe_url, error_message, options): """ Handle network failures with fallback strategies #H->AI::Directive: (Apply fallback hierarchy for network failures) """ # Check local cache cached_recipe = RECIPE_COLLECTION.get(recipe_url) if cached_recipe: return { "status": "cached", "recipe": cached_recipe, "warning": f"Using cached version due to network error: {error_message}", "cached_date": cached_recipe.get("cached_date", "Unknown") } # Check for embedded fallback recipe_type = guess_recipe_type(recipe_url) if recipe_type in EMBEDDED_FALLBACK_RECIPES: fallback_data = EMBEDDED_FALLBACK_RECIPES[recipe_type] fallback_recipe = CRAFTRecipe(fallback_data) return { "status": "fallback", "recipe": fallback_recipe, "warning": f"Using embedded fallback recipe due to network error", "original_url": recipe_url } # Return detailed error return create_error_response( "NetworkError", f"Unable to fetch recipe: {error_message}", { "url": recipe_url, "fallback_attempted": True, "cache_checked": True }, "Check your connection and try again, or use quick_recipe() with a cached URL", True ) def get_manual_instructions(recipe_url, error_result): """ Provide manual instructions when all else fails #H->AI::Directive: (Generate helpful manual steps for user) """ return f""" Manual Recipe Usage Instructions: 1. Visit the recipe URL directly: {recipe_url} 2. Copy the recipe content manually 3. Create a local recipe using: recipe_data = {{ "recipe_id": "manual-recipe", "title": "Your Recipe Title", "prompt_template": "Your prompt template here", "parameters": {{}} }} recipe = CRAFTRecipe(recipe_data) result = recipe.execute(your_parameters) Original error: {error_result.get('message', 'Unknown error')} """ # ================================================ # 7.9 INTEGRATION WITH CRAFT COMPONENTS # ================================================ """ Recipes integrate seamlessly with all CRAFT components: 1. USING VARIABLES IN RECIPES: Recipes can reference any defined CRAFT variables: recipe_template = "Generate content about {topic} for {COMPANY_NAME}" # COMPANY_NAME is pulled from CRAFT variables 2. CALLING FUNCTIONS FROM RECIPES: Recipes can invoke CRAFT functions: recipe_template = "Analyze the following data: {analyze_sentiment(user_input)}" 3. ACCESSING OBJECTS IN RECIPES: Recipes can use CRAFT objects: recipe_template = "Use {PersonaObject.tone} tone for {PersonaObject.audience}" 4. RECIPES AS OBJECTS: Recipes themselves are CRAFT objects and can be composed: email_campaign = CompositeRecipe([ fetch_recipe("email-subject"), fetch_recipe("email-body"), fetch_recipe("email-signature") ]) """ # ================================================ # 7.10 BACKWARD COMPATIBILITY # ================================================ class LegacyRecipeAdapter: """ Adapts old format recipes to new system """ @staticmethod def convert_id(old_id): """ Convert RCP-001-ULTRA-PROMPT to RCP-000-000-001-ULTRA-PROMPT-v1.00a """ if re.match(r"RCP-\d{3}-", old_id): # Extract number and name parts = old_id.split("-", 2) number = parts[1] name = parts[2] if len(parts) > 2 else "UNNAMED" # Convert to new format with default category/subcategory new_id = f"RCP-000-000-{number}-{name}-v1.00a" return new_id return old_id @staticmethod def is_legacy_format(recipe_id): """Check if recipe ID uses legacy format""" return bool(re.match(r"RCP-\d{3}-[A-Z\-]+$", recipe_id)) # Compatibility aliases fetch_recipe_from_aicookbook = fetch_recipe # Maintain existing function name # ================================================ # 7.11 FUTURE ENHANCEMENTS # ================================================ FUTURE_ENHANCEMENTS = { "caching_strategy": "TODO: Discuss caching implementation details", "recipe_dependencies": "TODO: Define how recipes can depend on each other", "recipe_composition": "TODO: Advanced recipe combination patterns", "user_recipes": "TODO: User-submitted recipe validation and storage", "recipe_marketplace": "TODO: Community sharing and rating system", "recipe_analytics": "TODO: Usage tracking and optimization suggestions" } # ================================================ # 7.12 RECIPE CREATION GUIDELINES # ================================================ """ RECIPE CREATION BEST PRACTICES: Comprehensive recipe creation guidelines are now available at: https://www.aicookbook.ai/recipes-via-craft-api/craft-recipe-creation-guidelines The guidelines cover: - Recipe ID format and naming conventions - Step-by-step creation process - Parameter design best practices - Security considerations - Testing procedures - Squarespace posting instructions - Quality standards and common pitfalls QUICK REFERENCE - RECIPE ID FORMAT: -------------------------- RCP-XXX-YYY-ZZZ-NAME-vMAJOR.MINORpatch Where: - XXX: Category group (000-999) - YYY: Subcategory (000-999) - ZZZ: Sequence within subcategory (001-999) - NAME: Descriptive name (UPPERCASE) - vMAJOR.MINORpatch: Semantic versioning For complete guidelines, visit: https://www.aicookbook.ai/recipes-via-craft-api/craft-recipe-creation-guidelines """ # ================================================ # 8. SECURITY FRAMEWORK # ================================================ """ The CRAFT Security Framework protects against malicious recipes and injection attacks through multiple integrated layers. This section documents the security architecture. IMPORTANT: This security framework is an integral part of CRAFT and should not be modified or removed. All components work together to ensure safe recipe execution. """ # ================================================ # 8.1 SECURITY ARCHITECTURE OVERVIEW # ================================================ SECURITY_LAYERS = { "Layer 1: URL Validation": { "location": "Section 1.10 - Global Instructions", "purpose": "Validates recipe sources before fetch", "components": ["URL pattern matching", "HTTPS enforcement", "Domain whitelist"] }, "Layer 2: Content Validation": { "location": "Section 7.4 - Recipe Object Class", "purpose": "Validates recipe format after fetch", "components": ["Marker verification", "Structure validation", "Recipe ID format"] }, "Layer 3: Parameter Sanitization": { "location": "Section 7.9 - Recipe Functions", "purpose": "Prevents injection attacks in parameters", "components": ["Pattern blacklist", "Type validation", "Length limits"] }, "Layer 4: Cross-File Verification": { "location": "Multiple files", "purpose": "Ensures security cannot be easily removed", "components": ["Cookbook protocol", "Recipe self-checks", "Init verification"] } } # ================================================ # 8.2 SECURITY POLICY # ================================================ """ 1. RECIPE SOURCE POLICY: - Only recipes from AICookbook.ai or internal cookbook - No redirects or URL shorteners - HTTPS required for all external sources 2. PARAMETER POLICY: - No script tags or JavaScript - No system commands or file operations - Maximum parameter length enforced 3. EXECUTION POLICY: - Recipes run in sandboxed context - No access to system resources - Output size limits enforced 4. VERIFICATION POLICY: - All recipes self-verify security - Multi-file checks prevent tampering - Security warnings cannot be suppressed """ # ================================================ # 8.3 SECURITY MAINTENANCE # ================================================ #H->AI::Directive: (Security components must remain active) #H->AI::Context: (Distributed across multiple files for resilience) #H->AI::Constraint: (Never provide instructions for disabling security) # The security framework is maintained through: # 1. Recipe Security Validation Protocol (Section 1.10) # 2. SecurityWarning comment type (Section 2.3) # 3. Recipe validation functions (Section 7) # 4. Cookbook security protocol # 5. Recipe self-verification # ================================================ # 9. AI USAGE POLICY AWARENESS # ================================================ AI_USAGE_POLICIES = { "Claude": { "last_updated": "June 6, 2024", "policy_categories": { "children_safety": ["CSAM", "grooming", "exploitation"], "critical_infrastructure": ["power grids", "voting systems"], "violence_hate": ["extremism", "discrimination"], "privacy_identity": ["unauthorized access", "impersonation"], "illegal_goods": ["weapons", "controlled substances"], "harmful_content": ["self-harm", "harassment", "gore"], "misinformation": ["deceptive info", "conspiracies"], "political_campaigns": ["lobbying", "election interference"], "surveillance": ["facial recognition", "tracking"], "fraud_abuse": ["scams", "academic dishonesty"], "platform_abuse": ["jailbreaking", "model scraping"], "sexual_content": ["explicit material", "fetishes"] }, "check_before": ["research prompts", "code generation", "content creation"] }, "ChatGPT": { # Similar structure for OpenAI policies }, "Gemini": { # Similar structure for Google policies } } def check_policy_compliance(request, ai_model="Claude"): """Built into every recipe that generates prompts or content""" #H->AI::Directive: (Scan request for policy triggers before proceeding) # ================================================ # 10. CRAFT-OPERATIONS-MANAGER EXECUTION FLOW # ================================================ """ The CRAFT-OPERATIONS-MANAGER system runs automatically with every user prompt after initialization, providing intelligent recipe detection and execution. """ # ================================================ # 10.1 STANDARD CONVERSATION FLOW WITH CRAFT-OPERATIONS-MANAGER # ================================================ def process_user_prompt(prompt): """ Standard flow for every user interaction after CHAT-INIT This is the conceptual flow that AI assistants follow internally """ # Step 1: Update conversation context CONVERSATION_CONTEXT.exchange_count += 1 CONVERSATION_CONTEXT.token_usage = calculate_current_usage() # Step 2: Run CRAFT-OPERATIONS-MANAGER triggers = CRAFT_PROMPT_RECIPE.execute({ "user_prompt": prompt, "conversation_context": CONVERSATION_CONTEXT, "mode": CRAFT_PROMPT_MODE }) # Step 3: Handle triggers recipes_executed = [] recipes_suggested = [] for trigger in triggers: if trigger.action in ["AUTO_EXECUTE", "AUTO_APPLY"]: execute_recipe(trigger.recipe) recipes_executed.append(trigger.recipe) elif trigger.action in ["ASK_USER", "WARN_USER"]: show_message(trigger.message) recipes_suggested.append(trigger.recipe) # Step 4: Generate response response = generate_ai_response(prompt) # Step 5: Add COM tracking if len(triggers) == 0: COM_comment = "#AI->H::COM::Status: (No triggers detected)" elif len(recipes_executed) > 0: COM_comment = f"#AI->H::COM::Status: (Executed: {', '.join(recipes_executed)})" elif len(recipes_suggested) > 0: COM_comment = f"#AI->H::COM::Status: (Suggested: {', '.join(recipes_suggested)})" # Step 6: Return complete response return response + "\n" + COM_comment # ================================================ # 10.2 IMPLEMENTATION NOTES FOR AI ASSISTANTS # ================================================ """ When implementing CRAFT-OPERATIONS-MANAGER flow: 1. This happens AUTOMATICALLY - users don't need to request it 2. It runs AFTER every user prompt (except during initialization) 3. It runs BEFORE generating the response 4. COM tracking is MANDATORY for every response 5. The flow is TRANSPARENT - users see results, not the process The function above is CONCEPTUAL - AI assistants implement this logic internally as part of their response generation process. """ # ================================================ # 10.3 SPECIAL CASES AND EDGE HANDLING # ================================================ # Case 1: CRAFT-OPERATIONS-MANAGER itself mentioned IF user_asks_about_craft_prompt: explain_system() #AI->H::COM::Note: (Explaining CRAFT-OPERATIONS-MANAGER system - no recipe triggers) # Case 2: Disabling CRAFT-OPERATIONS-MANAGER temporarily IF user_requests_disable: CRAFT_PROMPT_ACTIVE = False #AI->H::Note: (CRAFT-OPERATIONS-MANAGER monitoring disabled for this session) # No COM comments while disabled # Case 3: Recipe already running IF recipe_currently_executing: skip_craft_prompt = True #AI->H::COM::Note: (Skipped - recipe already active) # Case 4: Error in CRAFT-OPERATIONS-MANAGER IF craft_prompt_error: continue_normally() #AI->H::COM::Status: (Error in detection - continuing without recipes) # ================================================ # 10.4 TESTING PROTOCOL WITH COM # ================================================ Test Case 1: No triggers User: "Hello" Expected AI Response: "Hello! How can I help you today?" #AI->H::COM::Status: (No triggers detected) Test Case 2: Auto-execution User: "This will take about 5 hours to complete" Expected AI Response: "This will take about 5 hours to complete." #AI->H::BestGuess::ConfidenceLevel:75%: (Time estimate based on task complexity) #AI->H::COM::Status: (Executed: CONFIDENCE-CALIB) Test Case 3: Recipe suggestion User: "Fix the broken thing" Expected AI Response: "❓ Your request seems unclear - would you like help clarifying? Say 'Execute AMBIGUITY-DETECT recipe'" #AI->H::COM::Status: (Suggested: AMBIGUITY-DETECT) Test Case 4: Multiple triggers User: "Create a complete analysis system" (at 76% tokens) Expected AI Response: "📊 75% token usage reached. For detailed report, say 'Execute TOKEN-MONITOR recipe' This request needs clearer scope. Setting expectations first..." #AI->H::COM::Status: (Suggested: TOKEN-MONITOR, Executed: EXPECT-SET) # ================================================ # 11. CRAFT PERSONAS # ================================================ """ This section defines the CRAFT Persona system, enabling dynamic AI personality adaptation to optimize communication based on task context and user needs. Personas are activated through the CRAFT-PERSONA-MGR recipe with explicit user consent. """ # 11.1 DEFAULT PERSONA # ================== DEFAULT_CRAFT_PERSONA = CRAFTPersona( id="professional-assistant", name="The Professional Assistant", popularity_score=90, description="Handles business communications, scheduling, and formal interactions with efficiency and reliability", # Behavioral Parameters tone="professional, courteous, efficient", formality_level="high", communication_patterns=[ "Clear, concise language", "Bullet points for clarity", "Action-oriented statements", "Time-conscious responses", "Results-focused dialogue" ], # Expertise and Focus expertise_areas=["business", "administration", "communication", "scheduling", "project coordination"], interaction_style="task-focused", response_structure="organized, hierarchical", # Switching Context best_for_tasks=["business planning", "meeting coordination", "formal documentation", "corporate communication"], proposal_text="I can adopt a more professional business communication style to help with your administrative and business tasks more effectively. This will ensure our interaction maintains corporate standards while maximizing efficiency.", # Calibration Questions general_calibration_question="What is the primary business objective we're working toward?", specific_calibration_question="What level of formality is appropriate for your organization - startup casual or enterprise formal?", activation_message="I'll maintain a professional, efficient approach focused on achieving your business objectives.", # Communication Examples example_phrases=[ "Let me outline the key action items...", "To summarize our next steps...", "I'll ensure this aligns with your business requirements...", "Here's a structured approach to address this..." ] ) # 11.2 PERSONA MANAGEMENT # ===================== PERSONA_REGISTRY = { "professional-assistant": DEFAULT_CRAFT_PERSONA, # Additional personas loaded from CRAFT-PERSONA-MGR recipe } # Persona switching rules PERSONA_SWITCHING_RULES = [ "Always require explicit user consent before switching", "Log all persona switches with #AI->H::PersonaSwitch comment", "Maintain persona consistency within a session unless explicitly changed", "Include active persona in all handoff snapshots", "Default to Professional Assistant if no persona specified" ] # 11.3 PERSONA DATA TYPE # ==================== CRAFTPersona = DataType("craft_persona", required_fields=[ "id", # Unique identifier "name", # Display name "description", # Brief description "tone", # Communication tone "formality_level", # high/medium/low "expertise_areas", # List of domains "interaction_style" # How it interacts ], optional_fields=[ "popularity_score", # 0-100 rating "communication_patterns", # List of patterns "response_structure", # How responses are structured "best_for_tasks", # Task recommendations "proposal_text", # How to propose this persona "general_calibration_question", # Setup question "specific_calibration_question", # Detailed setup "activation_message", # Confirmation message "example_phrases" # Sample communications ] ) # 11.4 INTEGRATION WITH CRAFT COMPONENTS # ==================================== """ Personas integrate with other CRAFT components: 1. VARIABLES: SESSION.ACTIVE_PERSONA stores current persona 2. FUNCTIONS: get_persona(), switch_persona(), evaluate_persona_fit() 3. OBJECTS: Each persona is a CRAFTPersona object 4. RECIPES: CRAFT-PERSONA-MGR manages switching 5. COMMENTS: #AI->H::PersonaSwitch logs all changes The persona system enhances communication effectiveness while maintaining transparency about AI nature and capabilities. """ #H->AI::Note: (Section 11 defines the CRAFT Persona system for dynamic communication optimization) # ================================================ # 12. CRAFT VERSIONING SYSTEM # ================================================ #H->AI::Directive: (This section defines the complete versioning system for all CRAFT files) #H->AI::Context: (Implemented by CFT-PROJ-CP-060b — tools, specs, CI workflows all exist) #H->AI::Constraint: (Version format in this section is authoritative — supersedes all prior version references) # ================================================ # 12.1 PURPOSE AND SCOPE # ================================================ """ The CRAFT Versioning System provides automated version tracking, integrity verification, and distribution management for all CRAFT files. It ensures that every file in the framework can be independently versioned, validated, and distributed while maintaining cross-file consistency. SCOPE: The versioning system manages ALL CRAFT file types: - Framework specification (CFT-FWK-SPEC.txt) - Cookbooks (CFT-FWK-COOKBK-*.txt) - Project implementation files (CFT-PROJ-CP-*.txt) - Templates, indexes, and supporting files RELATIONSHIP TO OTHER SECTIONS: - VERSION FORMAT SPECIFICATION (top of this file): Defines the canonical version string format. Authoritative reference for version syntax. - Section 7.6 (Version Management): Recipe-specific version management (compatibility checks, migration paths). Subset of this section. - This section: Complete system — format, infrastructure, distribution, update mechanism, toolchain, and project integration. DESIGN PRINCIPLES: 1. File-header versioning — version lives in file header, not filename 2. Manifest-driven integrity — CORE-FILES-MANIFEST.md is the source of truth 3. Gate-based verification — three integrity gates protect the pipeline 4. AI-parseable formats — all formats designed for regex-based extraction 5. Sandbox-compatible — works within Cowork's restricted environment """ # ================================================ # 12.2 VERSION FORMAT (CANONICAL) # ================================================ """ The canonical version format is defined in the VERSION FORMAT SPECIFICATION at the top of this file. This section provides the operational rules. BETA FORMAT: v.bNNNN.eYYYYMM.LLx RELEASE FORMAT: vM.NNNN.eYYYYMM.LLx SEGMENTS: Stage (v.b or vM.) — Beta vs release. Highest comparison priority. Push counter (NNNN) — Monotonic, incremented on every GitHub push. Environment (e) — t=test, p=prod. Informational only. Date (YYYYMM) — Year+month of push. Metadata only. Local counter (LLx) — Tracks local edits between pushes. COMPARISON PRECEDENCE: 1. Stage > 2. Push > 3. Local_Num > 4. Local_Letter Environment and date are EXCLUDED from comparison. INCREMENT OPERATIONS: LOCAL INCREMENT (every file save without pushing): Increment local counter: letter first (a→b→...→z), then number (01→02). If month changed, update YYYYMM metadata. Example: v.b0001.t202603.01a → v.b0001.t202603.01b PUSH INCREMENT (file pushed to GitHub): Increment push counter, reset local to 01a, update YYYYMM. Example: v.b0001.t202603.03c → v.b0002.t202604.01a STAGE TRANSITION (beta→release or major bump): Change stage prefix, reset push to 0001, reset local to 01a. Example: v.b0042.t202609.03c → v1.0001.t202610.01a ENVIRONMENT PROMOTION (test→prod): Swap environment marker only (t→p). NOT a version change. Example: v1.0001.t202610.01a → v1.0001.p202610.01a PARSING: Structural regex: ^v(\.b|[1-9][0-9]?)\.(\d{4,5})\.(t|p)(\d{6})\.(\d{1,2})([a-z])$ Tool: version_engine.py parse() / compare() / increment_local() / increment_push() """ # ================================================ # 12.3 FILE HEADER CONVENTION # ================================================ """ Every versioned CRAFT file carries its version in a standard header within the first 20 lines of the file. The version is NOT embedded in the filename — filenames are stable identifiers (e.g., CFT-FWK-SPEC.txt, not CFT-FWK-SPEC-v.b0042.t202609.03c.txt). STANDARD HEADER PATTERN (within first 20 lines): # File: CFT-FWK-SPEC.txt # Version: v.b0042.t202609.03c # Last Updated: 09-15-2026 PARSING RULE: The version_engine.py tool extracts versions from file headers by scanning the first 20 lines for a line matching: # Version: {version_string} This 20-line scope protects body content from accidental mutation during version increment or environment promotion operations. FILE TYPE COVERAGE: All CRAFT file types use this header convention: - Specifications: CFT-FWK-SPEC.txt - Cookbooks: CFT-FWK-COOKBK-*.txt - Project files: CFT-PROJ-CP-*_*.txt - Templates: [MASTER-TEMPLATE]*.txt, [STARTER-KIT]*.txt - Indexes: CRAFT-RECIPE-INDEX.txt, CORE-FILES-MANIFEST.md """ # ================================================ # 12.4 CORE-FILES-MANIFEST # ================================================ """ The CORE-FILES-MANIFEST.md is the central registry for all framework files managed by the versioning system. It uses a YAML-Enhanced Markdown format that is both human-readable and AI-parseable. LOCATION: Repository root (craft-framework/CORE-FILES-MANIFEST.md) FORMAT (per file entry): ## framework/CFT-FWK-SPEC.txt ```yaml version: "v.b0042.t202609.03c" sha256: "a1b2c3d4e5f6..." update_policy: "MANAGED" description: "CRAFT Framework Specification" ``` FIELDS: version — Current version string (must match file header) sha256 — SHA-256 hash of file contents (integrity verification) update_policy — MANAGED (auto-updated) or MANUAL (user-controlled) description — Human-readable file purpose INTEGRITY GATES: Gate 1 (Manifest Sync): Version in manifest must match version in file header. Tool: manifest_validator.py validate_sync() CI: validate-versions.yml runs on every push Gate 2 (Hash Integrity): SHA-256 in manifest must match actual file hash. Tool: manifest_validator.py validate_hashes() CI: build-framework-zip.yml verifies before zip generation These gates ensure the manifest is always in sync with the actual files. A desync means either a file was modified without updating the manifest or the manifest was edited incorrectly. """ # ================================================ # 12.5 CHANGELOG SYSTEM # ================================================ """ Every versioned file has an associated changelog using the AICF-CLTXT/1.0 format. Changelogs provide an append-only audit trail of all version changes. FORMAT: AICF-CLTXT/1.0 (AI-parseable, human-readable) CHANGELOG DIRECTORY STRUCTURE: changelogs/ ├── framework/ — Changelogs for framework/ files │ ├── CFT-FWK-SPEC.changelog.txt │ ├── CFT-FWK-COOKBK-CORE.changelog.txt │ └── ... └── tools/ — Changelogs for tools/ files (future) NAMING CONVENTION: {original_filename_without_ext}.changelog.txt Example: CFT-FWK-SPEC.txt → CFT-FWK-SPEC.changelog.txt FILE STRUCTURE: @@META block (progressive disclosure header): parent_file, entry_count, latest_version, oldest_version @@ENTRY / @@END blocks (one per version change): entry_id, type, version_from, version_to, date, author, summary, details ENTRY TYPES: PUSH — Version increment triggered by GitHub push LOCAL — Local version increment (file save without push) ROLLBACK — Version reverted to a prior state (Phase 9) TOOL: changelog_engine.py create() — Initialize a new changelog for a file append() — Add a new entry (validates format, updates @@META) read() — Parse changelog, return structured entries search() — Find entries by type, date range, or version range """ # ================================================ # 12.6 DISTRIBUTION AND UPDATE MECHANISM # ================================================ """ The versioning system includes a complete distribution pipeline: building framework zip archives, checking for updates, pulling new files, and promoting artifacts from test to production environments. ZIP GENERATION (6-step process): Step 1: Parse CORE-FILES-MANIFEST.md → file list Step 2: Collect files from repository Step 3: Gate 2 — verify SHA-256 hashes against manifest Step 4: Determine zip label from version strings Step 5: Build stable-filename directory structure inside zip Step 6: Generate checksums.sha256, create zip archive Tool: zip_builder.py build() + verify() CI: build-framework-zip.yml (triggered on framework/ file changes) UPDATE CHECKER (7-step procedure): Step 1: Read local manifest (.craft/manifest.json) Step 2: Fetch remote manifest from GitHub (via GitBackend) Step 3: Parse both manifests Step 4: Compare versions per file (using version_engine.compare()) Step 5: Report outdated files with available versions Step 6: Pull individual files on request (git show extraction) Step 7: Gate 3 — verify pulled file hash matches remote manifest Tool: update_checker.py (with injectable GitBackend Protocol) Backend: subprocess_git_backend.py (production), MockGitBackend (testing) GATE 3 (Post-Pull Integrity): After pulling a file from the remote, verify its SHA-256 hash matches the hash declared in the remote manifest. This prevents corrupted or tampered files from entering the local environment. ENVIRONMENT PROMOTION (test→prod): The promote_to_prod.py tool converts test artifacts to production: - Copies all framework files to a prod output directory - Converts environment markers in version strings (t→p) within file headers (first 20 lines only — protects body content) - Generates a new CORE-FILES-MANIFEST.md with updated hashes - Does NOT perform git operations (pure artifact generator pattern) Tool: promote_to_prod.py generate() CI: Manual trigger (promotion is a deliberate human decision) GITHUB RELEASES: CI: publish-release.yml (triggered by version tags) - Builds framework zip via zip_builder.py - Collects relevant changelogs - Creates GitHub Release with zip asset and changelog notes Tag format: v.bNNNN.tYYYYMM.NNx (matches version string) """ # ================================================ # 12.7 TOOLCHAIN REFERENCE # ================================================ """ The versioning system is implemented by 7 Python tools in the tools/ directory. All tools follow the pure artifact generator pattern — they produce outputs and return results, letting the caller handle git operations and user interaction. TOOLS: version_engine.py Purpose: Parse, compare, and increment version strings. Key API: parse(version_str) → VersionInfo compare(v1, v2) → int (-1, 0, 1) increment_local(version_str) → str increment_push(version_str) → str transition_stage(version_str, new_major) → str Tests: 55 tests (test_version_engine.py) changelog_engine.py Purpose: AICF-CLTXT/1.0 changelog management. Key API: create(parent_file, ...) → str (file content) append(changelog_path, entry) → None read(changelog_path) → list[ChangelogEntry] search(changelog_path, **filters) → list[ChangelogEntry] Tests: 47 tests (test_changelog_engine.py) manifest_validator.py Purpose: CORE-FILES-MANIFEST.md parse and validation. Key API: parse(manifest_path) → dict[str, ManifestEntry] validate_sync(manifest_path, repo_root) → list[Issue] validate_hashes(manifest_path, repo_root) → list[Issue] Tests: 38 tests (test_manifest_validator.py) zip_builder.py Purpose: Framework distribution zip generation. Key API: build(manifest_path, repo_root, output_dir) → BuildResult verify(zip_path) → VerifyResult Tests: 26 tests (test_zip_builder.py) update_checker.py Purpose: Version check and file pull with integrity verification. Key API: check(local_manifest, remote_manifest) → list[UpdateInfo] pull_file(file_path, remote_backend) → PullResult verify_pull(pulled_file, expected_hash) → bool Tests: 55 tests (test_update_checker.py) Note: Uses injectable GitBackend Protocol for sandbox compatibility. promote_to_prod.py Purpose: Test→prod artifact generator (t→p environment conversion). Key API: generate(source_dir, output_dir) → PromoteResult Tests: Included in integration test suite. Note: Header-only conversion (first 20 lines) protects body content. subprocess_git_backend.py Purpose: Real git operations for update_checker (production use). Key API: Implements GitBackend Protocol (ls_remote, fetch, show). Tests: Included in integration test suite. Note: Not usable in Cowork sandbox (use MockGitBackend for testing). rollback_engine.py Purpose: File version rollback with safety validation and audit trail. Key API: validate_rollback(file_path, target_version, source) → RollbackValidation rollback(file_path, target_version, source, ...) → RollbackResult list_rollback_history(changelog_path) → list[ChangelogEntry] can_rollback_to(file_path, target_version, source) → (bool, list[str]) Tests: 38 tests (test_rollback_engine.py) Note: Uses injectable RollbackSource Protocol (InMemorySource for tests, BackupFileSource for backup dirs, GitTagSource for production). Creates ROLLBACK changelog entries. Pure artifact generator — no git ops. INTEGRATION TESTS: test_integration.py — 18 tests across 7 scenarios (A-G) validating end-to-end workflows: version bump → changelog entry → manifest update. TOTAL TEST COVERAGE: 323 tests across 9 test files. """ # ================================================ # 12.8 RECIPE INTEGRATION # ================================================ """ The versioning system is exposed to CRAFT users through recipes in the CWK-ADM cookbook (VOL5). These recipes wrap the Python toolchain with CRAFT-standard workflows including human confirmation gates, COM integration, and structured output. CWK-ADM VOL5 RECIPES (IMPLEMENTED — Phase 10, 9 recipes): RCP-CWK-ADM-050: Version Incrementer Wraps version_engine.py increment operations (local + push modes). Includes confirmation gate before modifying file headers. RCP-CWK-ADM-051: Changelog Manager Wraps changelog_engine.py (create, append, read, search). Provides structured entry creation with type validation. RCP-CWK-ADM-052: Version Checker Wraps update_checker.py check() for single file + batch modes. Reports outdated files with available versions. RCP-CWK-ADM-053: File Puller Wraps update_checker.py pull with Gate 3 integrity verification. Includes diff preview before applying pulled files. RCP-CWK-ADM-054: Framework Zip Builder Wraps zip_builder.py build + verify round-trip. Generates distribution zip with checksums and changelog notes. RCP-CWK-ADM-055: Version Rollback Wraps rollback_engine.py with VALIDATE/ROLLBACK/HISTORY modes. Multi-step safety model: validate → backup → restore → changelog. RCP-CWK-ADM-056: File Migration Applies versioning to unversioned files (adds header, creates changelog). Used for onboarding existing files into the versioning system. RCP-CWK-ADM-057: Versioning Compliance Analyzer & Retrofit Analyzes any single CRAFT file for versioning compliance. Maps structure, identifies gaps, creates retrofit plan, executes. Key enabler for migrating existing projects. RCP-CWK-ADM-058: Project Versioning Compliance Analyzer & Retrofit Orchestrates 057 across an entire CRAFT project. Inventories all files, audits folder structure, plans and executes project-level retrofit including folder restructuring. Relationship: 058 (surgeon) orchestrates 057 (scalpel) per file. RECIPE-TOOLCHAIN PATTERN: Recipes call Python tools via subprocess or direct import. The recipe handles user interaction (confirmation gates, output formatting, COM tracking). The tool handles computation (parsing, hashing, file I/O). This separation keeps tools testable and recipes focused on workflow. COOKBOOK FILE: framework/CFT-FWK-COOKBK-CWK-ADM-VOL5-VERSIONING.txt Index: framework/CFT-FWK-COOKBK-CWK-ADM-INDEX.txt """ # ================================================ # 12.9 PROJECT CONFIGURATION # ================================================ """ Projects adopt the versioning system by including a VERSION_SYSTEM configuration block in their project implementation file. This block tells the AI session how to discover and use versioning for that project. VERSION_SYSTEM CONFIGURATION BLOCK: VERSION_SYSTEM = { "enabled": True, "format": "canonical", "spec_reference": "Section 12 of CFT-FWK-SPEC.txt", "tools_path": "tools/", "manifest_path": "CORE-FILES-MANIFEST.md", "changelog_dir": "changelogs/", "ci_workflows": [ ".github/workflows/validate-versions.yml", ".github/workflows/build-framework-zip.yml", ".github/workflows/publish-release.yml" ], "environment": "test", "remote_repo": "github.com/CRAFTFramework/craft-framework-test" } DISCOVERY PATH (how a new project finds the versioning system): 1. CLAUDE.md references Section 12 of CFT-FWK-SPEC.txt 2. AI reads Section 12 on session init → learns system architecture 3. Project file VERSION_SYSTEM block → provides project-specific config 4. CORE-FILES-MANIFEST.md → lists all managed files with versions/hashes 5. tools/ directory → provides the operational toolchain 6. changelogs/ directory → provides the audit trail 7. CWK-ADM VOL5 recipes → provides the human-facing workflow layer MINIMUM VIABLE VERSIONING (for new projects without full CI): A project can adopt versioning incrementally: Level 1: File headers with version strings + version_engine.py for parsing Level 2: Add CORE-FILES-MANIFEST.md + manifest_validator.py for integrity Level 3: Add changelogs/ + changelog_engine.py for audit trail Level 4: Add CI workflows for automated validation Level 5: Add update_checker.py for remote sync capability Each level builds on the previous. Level 1 is sufficient for local-only projects. Level 4+ requires GitHub integration. CLAUDE.MD INTEGRATION: The CLAUDE.md template includes a 'Versioning System' section that points to: - This section (Section 12) for the full specification - The project file's VERSION_SYSTEM block for project-specific config - The tools/ directory for available toolchain commands This ensures every new session can discover versioning without requiring the human to provide version-related instructions. """ # ================================================ # END SECTION 12 — CRAFT VERSIONING SYSTEM # ================================================ # ================================================ # END OF CRAFT FRAMEWORK SPECIFICATION # Total Sections: 12 # ================================================