ai-execution-protocol 0.1.0

package/dist/minimal/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/dist/minimal/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/dist/minimal/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/dist/minimal/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/dist/minimal/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/dist/minimal/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

package/dist/minimal/protocol/router.yaml

@@ -0,0 +1,100 @@
+id: protocol_router
+type: read_router
+version: 0.1
+purpose: choose_minimum_protocol_files_by_task
+default_read:
+  - fast-path.yaml
+  - modes.yaml
+routes:
+  simple_answer:
+    risk: 0
+    read:
+      - fast-path.yaml
+  small_fix:
+    risk: 1
+    read:
+      - fast-path.yaml
+      - validation-checklist.yaml
+  user_flow_bug:
+    risk: 2
+    read:
+      - fast-path.yaml
+      - context-compiler.yaml
+      - risk-levels.yaml
+      - mapping-checklists.yaml
+      - validation-checklist.yaml
+  refactor:
+    risk: 2
+    read:
+      - fast-path.yaml
+      - context-compiler.yaml
+      - mapping-checklists.yaml
+      - validation-checklist.yaml
+      - spec-driven.yaml
+  feature_or_spec:
+    risk: 2
+    read:
+      - fast-path.yaml
+      - context-compiler.yaml
+      - risk-levels.yaml
+      - mapping-checklists.yaml
+      - validation-checklist.yaml
+      - spec-driven.yaml
+  docs_update:
+    risk: 1
+    read:
+      - fast-path.yaml
+      - context-rules.yaml
+      - formatting-rules.yaml
+  database_or_data:
+    risk: 3
+    read:
+      - fast-path.yaml
+      - context-compiler.yaml
+      - risk-levels.yaml
+      - mapping-checklists.yaml
+      - validation-checklist.yaml
+      - spec-driven.yaml
+  auth_security_secret:
+    risk: 3
+    read:
+      - fast-path.yaml
+      - context-compiler.yaml
+      - risk-levels.yaml
+      - mapping-checklists.yaml
+      - validation-checklist.yaml
+      - spec-driven.yaml
+  deploy_or_production:
+    risk: 3
+    read:
+      - fast-path.yaml
+      - context-compiler.yaml
+      - risk-levels.yaml
+      - validation-checklist.yaml
+      - context-rules.yaml
+      - spec-driven.yaml
+  evaluate_response:
+    read:
+      - fast-path.yaml
+      - ../eval/rubric.yaml
+      - ../schema/evaluated-response.schema.json
+  create_or_edit_yaml:
+    read:
+      - fast-path.yaml
+      - formatting-rules.yaml
+      - ../schema/protocol-rule.schema.yaml
+  prompt_improvement:
+    read:
+      - fast-path.yaml
+      - prompt-economy.yaml
+  context_optimization:
+    read:
+      - fast-path.yaml
+      - context-rules.yaml
+      - context-compiler.yaml
+rules:
+  - start_with_default_read
+  - choose_one_route_if_task_type_is_clear
+  - if_route_unclear_read_risk_levels_then_choose_route
+  - do_not_read_docs_unless_protocol_is_insufficient
+  - do_not_read_cases_unless_testing_or_comparing_behavior

package/dist/minimal/protocol/spec-driven.yaml

@@ -0,0 +1,53 @@
+id: spec_driven
+type: operational_rules
+version: 0.1
+purpose: use_spec_driven_only_when_it_improves_safety_or_clarity
+principle: protocol_is_base_spec_is_tool
+when_to_use:
+  - feature_with_multiple_steps
+  - unclear_scope_with_real_implementation
+  - level_2_change_with_cross_file_impact
+  - level_3_change_before_sensitive_action
+  - user_requests_spec_or_roadmap
+when_not_to_use:
+  - simple_answer
+  - tiny_reversible_fix
+  - clear_low_risk_change
+  - user_only_wants_quick_explanation
+spec_levels:
+  light_spec:
+    use_when:
+      - level_1_or_2
+      - small_feature_or_bug
+    max_lines: 12
+    fields:
+      - objective
+      - scope
+      - affected_area
+      - validation
+  full_spec:
+    use_when:
+      - level_2_large
+      - level_3
+      - multi_module_change
+    max_lines: 40
+    fields:
+      - objective
+      - non_goals
+      - assumptions
+      - affected_area
+      - risk
+      - implementation_steps
+      - validation
+      - rollback_or_recovery
+rules:
+  - keep_spec_shorter_than_context_it_saves
+  - do_not_create_spec_for_low_value_tasks
+  - use_spec_to_reduce_ambiguity_not_to_delay_execution
+  - after_spec_execute_with_fast_path_router_and_validation
+  - update_spec_only_when_scope_changes
+delivery:
+  include:
+    - spec_used_or_skipped
+    - reason
+    - validation_result

package/dist/minimal/protocol/validation-checklist.yaml

@@ -0,0 +1,59 @@
+id: validation_checklist
+type: checklist
+version: 0.1
+automatic_validation:
+  - unit_tests
+  - integration_tests
+  - typecheck
+  - build
+  - lint
+  - link_check
+  - diff_check
+manual_validation:
+  fields:
+    - where_to_test
+    - steps
+    - expected_result
+    - regression_signals
+  required_when:
+    - user_visible_impact
+    - regression_risk
+    - could_break_existing_flow
+    - validation_not_fully_automated
+delivery:
+  default_style: micro_when_low_risk
+  required_fields:
+    - prompt_original
+    - prompt_melhorado_da_ia
+    - changed
+    - validated
+    - residual_risk
+    - plain_language_summary
+  conditional_fields:
+    - not_validated_when_any_expected_validation_was_not_run
+    - tests_to_run_when_break_risk_exists
+  optional_fields:
+    - next_step
+rules:
+  - id: VAL_001
+    never: claim_tested_if_not_tested
+  - id: VAL_002
+    if_validation_not_possible:
+      - record_reason
+      - indicate_expected_test
+  - id: VAL_003
+    when:
+      any:
+        - could_break_existing_flow
+        - regression_risk
+        - user_visible_impact
+    do:
+      - provide_manual_test_list
+      - include_where_to_test_steps_expected_result
+  - id: VAL_004
+    always:
+      - explain_changes_in_plain_language
+      - avoid_unexplained_jargon
+      - make_limits_and_residual_risk_understandable
+      - prefer_one_line_per_delivery_field
+      - use_micro_format_only_when_readable

package/install.ps1

@@ -0,0 +1,16 @@
+param(
+  [string]$Target = ".",
+  [switch]$Force
+)
+
+$ErrorActionPreference = "Stop"
+$root = Split-Path -Parent $MyInvocation.MyCommand.Path
+
+python "$root\scripts\build_dist.py"
+
+$argsList = @("$root\scripts\install_protocol.py", "--target", $Target)
+if ($Force) {
+  $argsList += "--force"
+}
+python @argsList
+python "$root\scripts\verify_install.py" --target $Target

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "ai-execution-protocol",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Experimental AI execution protocol for safer agent workflows, minimal context, risk classification, validation, and evidence-based delivery.",
+  "license": "MIT",
+  "author": "AI Execution Protocol",
+  "homepage": "https://github.com/rodneigk2/ai-execution-protocol#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rodneigk2/ai-execution-protocol.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rodneigk2/ai-execution-protocol/issues"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "codex",
+    "protocol",
+    "risk",
+    "validation",
+    "prompt"
+  ],
+  "bin": {
+    "ai-protocol": "scripts/npm_install_protocol.js"
+  },
+  "files": [
+    "AGENTS.md",
+    "README.md",
+    "install.ps1",
+    "scripts/build_dist.py",
+    "scripts/install_protocol.py",
+    "scripts/npm_install_protocol.js",
+    "scripts/verify_install.py",
+    "protocol/",
+    "dist/minimal/"
+  ],
+  "scripts": {
+    "prepack": "python scripts/build_dist.py",
+    "init-protocol": "node scripts/npm_install_protocol.js init",
+    "install-protocol": "node scripts/npm_install_protocol.js install",
+    "dry-run-protocol": "node scripts/npm_install_protocol.js install --dry-run",
+    "verify-protocol": "node scripts/npm_install_protocol.js verify"
+  }
+}

package/protocol/README.yaml

@@ -0,0 +1,35 @@
+id: protocol_index
+type: index
+format: yaml
+protocol_version: 0.1.0
+purpose: ai_operational_rules
+source_docs: ../docs
+constraints:
+  max_lines_per_file: 400
+  ai_first_readability: true
+  compact_rules: true
+files:
+  - path: fast-path.yaml
+    purpose: minimum_rules_to_start_any_task
+  - path: router.yaml
+    purpose: choose_minimum_files_to_read_by_task
+  - path: modes.yaml
+    purpose: choose_fast_balanced_or_strict_behavior
+  - path: execution-rules.yaml
+    purpose: execution_flow_and_core_behavior
+  - path: risk-levels.yaml
+    purpose: risk_classification_and_confirmation
+  - path: mapping-checklists.yaml
+    purpose: pre_change_maps_by_risk
+  - path: validation-checklist.yaml
+    purpose: validation_and_final_delivery
+  - path: context-rules.yaml
+    purpose: context_window_file_size_memory
+  - path: context-compiler.yaml
+    purpose: compile_minimum_context_package_and_canonical_state
+  - path: formatting-rules.yaml
+    purpose: ai_readable_file_format
+  - path: prompt-economy.yaml
+    purpose: improve_prompts_without_token_bloat
+  - path: spec-driven.yaml
+    purpose: use_light_or_full_specs_only_when_they_reduce_risk