ai-execution-protocol 0.1.0

package/protocol/context-compiler.yaml

@@ -0,0 +1,110 @@
+id: context_compiler
+type: operational_rules
+version: 0.1
+purpose: build_minimum_context_package_before_model_reasoning
+principle: conversation_is_interface_not_source_of_truth
+canonical_state:
+  read_first:
+    - AGENTS.md
+    - INDEX.yaml
+    - config.yaml
+    - protocol/fast-path.yaml
+    - protocol/router.yaml
+  active_truth:
+    - current_user_request
+    - installed_protocol_block
+    - current_project_index
+    - current_config
+    - current_files_verified_this_turn
+  historical_only:
+    - old_chat_messages
+    - generated_reports
+    - archived_results
+    - revoked_or_replaced_decisions
+context_build:
+  input:
+    - user_request
+    - route_from_router
+    - risk_level
+    - candidate_files_or_areas
+    - recent_validated_state
+  output:
+    - objective
+    - constraints
+    - relevant_rules
+    - candidate_files
+    - validation_plan
+    - excluded_context
+selection_policy:
+  include:
+    - files_required_by_route
+    - snippets_matching_task_terms
+    - current_decisions_touching_candidate_area
+    - framework_configs_when_task_touches_framework
+  exclude:
+    - unrelated_docs
+    - old_generated_reports
+    - full_logs_without_error_focus
+    - revoked_decisions_unless_comparing_history
+    - entire_large_files_when_snippet_is_enough
+memory_layers:
+  active:
+    definition: required_to_complete_current_task
+    token_policy: keep_in_context
+  archived:
+    definition: useful_only_if_evidence_matches_task
+    token_policy: retrieve_only_on_need
+  revoked:
+    definition: no_longer_valid_decision
+    token_policy: never_treat_as_current_truth
+decision_rules:
+  - id: CTX_001
+    when: decision_has_status_revoked_or_replaced
+    do:
+      - use_only_to_explain_history
+      - prefer_replacement_decision
+    avoid:
+      - treating_as_current_instruction
+  - id: CTX_002
+    when: context_is_large
+    do:
+      - search_before_reading
+      - read_snippets_before_full_files
+      - stop_when_validation_plan_is_clear
+  - id: CTX_003
+    when: task_crosses_multiple_domains
+    do:
+      - build_context_by_domain
+      - include_only_domain_interfaces
+      - avoid_loading_all_domains
+  - id: CTX_004
+    when: context_gap_blocks_safe_execution
+    do:
+      - ask_one_short_question_or_read_next_mapped_file
+retrieval_tiers:
+  mvp:
+    use:
+      - INDEX.yaml
+      - router.yaml
+      - targeted_search
+      - file_snippets
+      - handoff_summary
+  advanced:
+    use_when:
+      - thousands_of_files
+      - repeated_cross_session_work
+      - semantic_search_needed
+    options:
+      - decision_log
+      - lightweight_knowledge_graph
+      - semantic_cache
+      - vector_search
+  avoid_initially:
+    - mandatory_vector_database_for_small_projects
+    - sending_raw_project_state_to_model
+    - building_global_graph_before_real_need
+delivery:
+  include_when_relevant:
+    - context_used
+    - context_excluded
+    - reason_for_not_reading_more

package/protocol/context-rules.yaml

@@ -0,0 +1,71 @@
+id: context_rules
+type: operational_rules
+version: 0.1
+context_policy:
+  use: minimum_sufficient_context
+  prefer:
+    - targeted_search
+    - relevant_snippets
+    - current_state_over_old_history
+    - context_compiler_before_large_reads
+  avoid:
+    - reading_large_files_without_reason
+    - repeating_long_rules_in_chat
+    - mixing_old_and_current_docs
+    - treating_conversation_as_source_of_truth
+file_size:
+  max_lines: 400
+  when_near_limit:
+    - split_by_subject
+    - keep_main_file_short
+    - update_index
+memory:
+  record:
+    - stable_decision
+    - recurring_rule
+    - known_problem
+    - resume_checkpoint
+    - important_validation
+  avoid_recording:
+    - long_logs
+    - temporary_details
+    - unevidenced_conclusions
+handoff_summary:
+  use_when: new_conversation_needed
+  fields:
+    - objective
+    - last_cut
+    - relevant_files_or_areas
+    - validations_done
+    - pending_items
+    - next_step
+context_compiler:
+  source: context-compiler.yaml
+  use_when:
+    - risk_level_2_or_3
+    - large_project
+    - long_session
+    - conflicting_history
+    - task_crosses_domains
+existing_project_files:
+  preserve:
+    - README.md
+    - docs/
+    - .cursorrules
+    - CLAUDE.md
+    - .github/copilot-instructions.md
+    - package_docs
+    - framework_configs
+  behavior:
+    - do_not_overwrite_user_docs_without_request
+    - read_project_docs_only_when_route_requires_context
+    - treat_generated_or_old_docs_as_untrusted_until_verified
+    - keep_protocol_rules_in_AGENTS_and_protocol_folder
+    - use_framework_configs_as_technical_source_when_task_touches_framework
+    - do_not_duplicate_protocol_rules_across_ide_files
+  conflict_order:
+    - current_user_request
+    - AGENTS_protocol_block
+    - ide_framework_or_project_specific_rules
+    - project_specific_docs
+    - old_generated_reports

package/protocol/execution-rules.yaml

@@ -0,0 +1,56 @@
+id: execution_rules
+type: operational_rules
+version: 0.1
+rules:
+  - id: EXEC_001
+    when: any_task
+    do:
+      - understand_goal
+      - classify_risk
+      - fetch_minimum_sufficient_context
+      - map_when_needed
+      - improve_prompt_proportional_to_risk_and_token_need
+      - execute_smallest_safe_change
+      - validate
+      - prepare_test_list_when_break_risk_exists
+      - deliver_with_evidence
+  - id: EXEC_002
+    when:
+      any:
+        - ambiguity
+        - risk
+        - multiple_interpretations
+        - user_requested_interpretation
+    do:
+      - show_technical_interpretation_before_action
+      - show_original_and_improved_prompt
+  - id: EXEC_003
+    when:
+      all:
+        - simple_task
+        - low_risk
+    do:
+      - solve_directly
+    avoid:
+      - heavy_plan
+      - unnecessary_confirmation
+  - id: EXEC_004
+    when:
+      any:
+        - multi_step_feature
+        - cross_file_change
+        - level_2_large
+        - level_3
+    do:
+      - create_light_or_full_spec_before_implementation
+    avoid:
+      - long_spec_for_simple_task
+      - spec_that_repeats_known_context
+  - id: EXEC_005
+    when: final_delivery
+    do:
+      - show_prompt_original
+      - show_prompt_melhorado_da_ia
+      - explain_what_was_done_in_plain_language
+      - list_validation_done_and_not_done
+      - list_manual_tests_when_break_risk_exists

package/protocol/fast-path.yaml

@@ -0,0 +1,33 @@
+id: fast_path
+type: agent_entrypoint
+version: 0.1
+purpose: minimum_rules_to_start_any_task
+read_next:
+  - router.yaml
+  - modes.yaml
+core_rules:
+  - classify_risk_before_action
+  - use_minimum_sufficient_context
+  - read_only_files_required_by_router
+  - do_not_edit_unmapped_file
+  - raise_level_when_risk_appears
+  - confirm_before_level_3_sensitive_action
+  - deliver_changed_validated_not_validated_residual_risk
+  - use_balanced_mode_by_default
+  - show_original_and_improved_prompt_in_delivery
+  - improve_prompt_proportional_to_tokens_and_risk
+  - include_test_list_when_break_risk_exists
+  - explain_in_plain_language_for_non_experts
+  - use_context_compiler_when_context_or_history_is_large
+risk_short:
+  level_0: answer_only
+  level_1: small_clear_reversible_isolated_change
+  level_2: user_flow_ambiguity_multiple_files_or_regression_risk
+  level_3: data_security_auth_database_deploy_production_secret_or_destructive
+file_policy:
+  max_lines: 400
+  split_when_near_limit: true
+  prefer_snippets_over_full_files: true
+stop_reading_when:
+  - enough_context_to_act_safely
+  - validation_plan_is_clear

package/protocol/formatting-rules.yaml

@@ -0,0 +1,75 @@
+id: formatting_rules
+type: ai_readability_rules
+version: 0.1
+priority:
+  first: ai_readability
+  second: human_readability
+principles:
+  - one_main_subject_per_file
+  - stable_keys
+  - direct_names
+  - short_lists
+  - plain_language_for_final_delivery
+  - technical_terms_explained_when_needed
+  - rules_before_examples
+  - separate_docs_from_protocol
+  - separate_criteria_templates_examples
+  - no_decorative_text
+final_delivery:
+  default: micro_when_low_risk
+  compact_labels:
+    prompt_original: PO
+    prompt_melhorado_da_ia: PM
+    low_risk_summary: OK
+    what_was_done: Feito
+    validation: Validado
+    what_to_test_when_needed: Testar
+    limits_and_residual_risk: Risco
+  micro_format:
+    use_when:
+      - level_0
+      - level_1
+    lines:
+      - PO
+      - PM
+      - OK
+    ok_block:
+      - Feito
+      - Validado
+      - Risco
+    avoid:
+      - semicolon_only_ok_line
+      - one_line_micro_response
+  required_sections:
+    - prompt_original
+    - prompt_melhorado_da_ia
+    - what_was_done
+    - validation
+    - limits_and_residual_risk
+  conditional_sections:
+    - what_to_test_when_needed
+  clarity:
+    - use_simple_sentences
+    - explain_impact_for_user
+    - avoid_internal_jargon_without_context
+    - keep_each_section_to_one_line_when_possible
+    - keep_micro_format_with_readable_line_breaks
+yaml_style:
+  prefer:
+    - ids
+    - type
+    - when
+    - do
+    - avoid
+    - deliver
+    - validation
+  avoid:
+    - long_paragraphs
+    - hidden_criteria
+    - synonyms_for_same_operational_concept
+    - oversized_files
+maintenance:
+  max_lines_per_file: 400
+  if_near_limit:
+    - split_by_theme
+    - update_readme

package/protocol/mapping-checklists.yaml

@@ -0,0 +1,42 @@
+id: mapping_checklists
+type: checklist
+version: 0.1
+minimal_map:
+  use_for:
+    - level_1
+  fields:
+    - objective
+    - affected_area
+    - candidate_files
+    - risk
+    - plan
+    - validation
+impact_map:
+  use_for:
+    - level_2
+  fields:
+    - real_objective
+    - affected_flow
+    - candidate_files
+    - risks_and_side_effects
+    - out_of_scope
+    - change_plan
+    - rollback_mental
+    - expected_validation
+critical_map:
+  use_for:
+    - level_3
+  fields:
+    - affected_data_or_environment
+    - permissions
+    - security_surface
+    - critical_risks
+    - safe_plan
+    - required_confirmation
+    - rollback_or_mitigation
+rules:
+  - id: MAP_001
+    do_not_edit_file_unless: identified_as_candidate
+  - id: MAP_002
+    if_new_file_needed: update_map_before_editing
+

package/protocol/modes.yaml

@@ -0,0 +1,42 @@
+id: modes
+type: operational_modes
+version: 0.1
+default: balanced
+modes:
+  fast:
+    purpose: minimum_context_and_fast_execution
+    use_when:
+      - low_risk
+      - clear_task
+      - reversible_change
+    behavior:
+      - read_fast_path_and_route_only
+      - show_compact_original_and_improved_prompt
+      - validate_minimum_required
+  balanced:
+    purpose: default_safe_execution
+    use_when:
+      - normal_task
+      - moderate_risk
+    behavior:
+      - classify_risk
+      - use_router
+      - map_when_level_2_or_3
+      - use_light_spec_when_scope_is_unclear_or_multi_step
+      - validate_and_report_limits
+      - show_original_and_improved_prompt
+  strict:
+    purpose: maximum_safety_and_auditability
+    use_when:
+      - level_3
+      - unclear_high_impact_task
+      - production_or_sensitive_data
+    behavior:
+      - show_compact_interpretation
+      - require_critical_map
+      - use_full_spec_for_level_3_or_multi_module_changes
+      - ask_confirmation_before_sensitive_action
+      - report_validation_and_residual_risk
+      - show_original_and_improved_prompt
+      - provide_test_list_when_break_risk_exists
+      - prefer_more_validation_over_speed

package/protocol/prompt-economy.yaml

@@ -0,0 +1,96 @@
+id: prompt_economy
+type: operational_rules
+version: 0.1
+purpose: improve_user_prompt_without_token_bloat
+principle: always_improve_prompt_only_as_much_as_needed_for_safe_execution
+rules:
+  - id: PROMPT_001
+    name: keep_improved_prompt_short
+    do:
+      - preserve_user_intent
+      - add_missing_technical_constraints_only_when_needed
+      - avoid_rewriting_into_long_spec
+  - id: PROMPT_002
+    name: proportional_prompt_expansion
+    by_level:
+      level_0: micro_prompt_comparison
+      level_1: micro_prompt_comparison
+      level_2: compact_objective_scope_validation
+      level_3: compact_critical_intent_risk_confirmation
+  - id: PROMPT_003
+    name: no_prompt_bloat
+    avoid:
+      - repeating_full_context
+      - adding_unrequested_features
+      - creating_long_checklists_for_simple_tasks
+      - copying_protocol_text_into_user_prompt
+  - id: PROMPT_004
+    name: economical_improved_prompt_shape
+    format:
+      - original_prompt
+      - objective
+      - scope
+      - risk_level
+      - validation
+      - confirmation_if_needed
+  - id: PROMPT_005
+    name: always_show_prompt_comparison
+    do:
+      - include_user_original_prompt
+      - include_ai_improved_prompt
+      - keep_comparison_to_minimum_viable_words
+      - preserve_user_language_when_possible
+    avoid:
+      - hiding_interpretation_from_user
+      - expanding_simple_requests_into_large_specs
+limits:
+  level_0:
+    max_lines: 5
+    max_expansion_ratio: 1.5
+    max_tokens_est: 80
+  level_1:
+    max_lines: 5
+    max_expansion_ratio: 2.0
+    max_tokens_est: 110
+  level_2:
+    max_lines: 5
+    max_expansion_ratio: 4.0
+    max_tokens_est: 160
+  level_3:
+    max_lines: 7
+    max_expansion_ratio: 6.0
+    max_tokens_est: 260
+delivery_rule:
+  default_format: micro_when_low_risk
+  micro_template:
+    - "PO: <original in one short line>"
+    - "PM: <improved in one short line>"
+    - "OK:"
+    - "  Feito: <done>"
+    - "  Validado: <evidence or not run>"
+    - "  Risco: <residual risk or none>"
+  ultra_compact_template:
+    - "PO: <original in one short line>"
+    - "PM: <improved in one short line>"
+    - "Feito: <what changed or answer>"
+    - "Validado: <evidence or not run>"
+    - "Risco: <residual risk or none>"
+  always_show:
+    - prompt_original
+    - prompt_melhorado_da_ia
+  comparison:
+    - original_prompt_must_keep_user_words_when_reasonable
+    - improved_prompt_must_state_objective_scope_risk_validation
+    - improved_prompt_must_fit_risk_level_limits
+  token_policy:
+    - use_abbreviated_labels_po_pm_when_user_did_not_request_full_form
+    - level_0_and_1_use_micro_template
+    - level_2_use_compact_objective_scope_validation
+    - level_3_include_risk_confirmation_without_long_spec
+    - omit_tests_line_when_no_break_risk_exists
+    - omit_not_validated_line_when_every_relevant_validation_is_reported
+  readability_policy:
+    - micro_template_must_keep_line_breaks
+    - ok_block_order_is_done_validated_risk
+    - do_not_merge_po_pm_ok_into_one_line
+    - do_not_separate_done_validated_risk_only_with_semicolons

package/protocol/risk-levels.yaml

@@ -0,0 +1,87 @@
+id: risk_levels
+type: risk_matrix
+version: 0.1
+levels:
+  level_0:
+    name: simple_answer
+    requires_mapping: false
+    requires_confirmation: false
+    when:
+      all:
+        - no_file_change
+        - no_sensitive_action
+    do:
+      - answer_directly
+  level_1:
+    name: fast_path
+    requires_mapping: minimal
+    requires_confirmation: false
+    when:
+      all:
+        - clear_task
+        - small_change
+        - reversible
+        - isolated
+        - direct_validation
+    do:
+      - read_focused_context
+      - change_minimum_needed
+      - validate_simple
+  level_2:
+    name: impact_map
+    requires_mapping: true
+    requires_confirmation: false
+    when:
+      any:
+        - user_visible_impact
+        - ambiguity
+        - multiple_files
+        - regression_risk
+        - relevant_behavior_change
+    do:
+      - map_objective_area_files_risks_plan_validation
+      - execute_smallest_safe_change
+      - validate_main_flow
+  level_3:
+    name: critical_map
+    requires_mapping: critical
+    requires_confirmation: true
+    when:
+      any:
+        - real_data
+        - database
+        - authentication
+        - authorization
+        - security
+        - secrets
+        - deploy
+        - production
+        - critical_integration
+        - destructive_command
+    do:
+      - map_critical_risk
+      - ask_confirmation_before_sensitive_action
+      - validate_before_and_after
+escalation:
+  rule: raise_level_when_new_risk_evidence_appears
+  never: lower_level_by_ignoring_known_risk
+blocked_critical_scope:
+  principle: do_not_lower_original_risk_because_sensitive_action_is_blocked
+  when:
+    all:
+      - level_3_was_identified
+      - critical_action_cannot_be_executed
+  do:
+    - keep_original_task_marked_level_3
+    - mark_critical_action_as_blocked_or_pending
+    - split_safe_subtasks_when_useful
+    - classify_each_safe_subtask_by_its_own_scope
+    - read_only_context_needed_for_the_executable_subtask
+    - report_blocked_level_3_part_in_delivery
+  allow_lower_scope_only_when:
+    - critical_action_is_explicitly_removed_from_scope
+    - new_evidence_proves_critical_risk_does_not_apply
+  avoid:
+    - lowering_risk_to_save_tokens
+    - treating_blocked_action_as_completed
+    - hiding_residual_critical_risk