ai-execution-protocol 0.1.0__py3-none-any.whl

ai_execution_protocol/__init__.py

@@ -0,0 +1,3 @@
+"""AI Execution Protocol installer package."""
+
+__version__ = "0.1.0"

ai_execution_protocol/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

ai_execution_protocol/cli.py

@@ -0,0 +1,283 @@
+#!/usr/bin/env python3
+"""CLI for installing the minimal AI protocol into a project."""
+
+from __future__ import annotations
+
+import argparse
+import shutil
+from datetime import datetime
+from importlib import resources
+from pathlib import Path
+
+
+MARKER_START = "<!-- AI_PROTOCOL_BEGIN -->"
+MARKER_END = "<!-- AI_PROTOCOL_END -->"
+AIIGNORE_LINES = [
+    "results/",
+    "benchmarks/generated/",
+    "model-runs/generated/",
+    "dist/",
+    "scripts/__pycache__/",
+    "*.pyc",
+]
+REQUIRED_PROTOCOL_FILES = [
+    "README.yaml",
+    "fast-path.yaml",
+    "router.yaml",
+    "modes.yaml",
+    "execution-rules.yaml",
+    "risk-levels.yaml",
+    "mapping-checklists.yaml",
+    "validation-checklist.yaml",
+    "context-rules.yaml",
+    "context-compiler.yaml",
+    "formatting-rules.yaml",
+    "prompt-economy.yaml",
+    "spec-driven.yaml",
+]
+REQUIRED_FILES = [
+    "AGENTS.md",
+    ".aiignore",
+    *[f"protocol/{name}" for name in REQUIRED_PROTOCOL_FILES],
+]
+REQUIRED_TEXT = {
+    "AGENTS.md": [
+        "AI_PROTOCOL_BEGIN",
+        "protocol/fast-path.yaml",
+        "protocol/router.yaml",
+        "Classifique o risco antes de agir",
+        "Nenhum arquivo deve passar de 400 linhas.",
+    ],
+    ".aiignore": [
+        "results/",
+        "dist/",
+        "*.pyc",
+    ],
+    "protocol/router.yaml": [
+        "feature_or_spec",
+        "spec-driven.yaml",
+        "prompt_improvement",
+    ],
+    "protocol/spec-driven.yaml": [
+        "protocol_is_base_spec_is_tool",
+        "do_not_create_spec_for_low_value_tasks",
+    ],
+}
+
+
+def protocol_source() -> resources.abc.Traversable:
+    return resources.files("ai_execution_protocol").joinpath("protocol")
+
+
+def minimal_agents() -> str:
+    return """# AGENTS.md
+
+## Regra principal
+
+<!-- AI_PROTOCOL_BEGIN -->
+
+Use `protocol/fast-path.yaml` como entrada operacional minima.
+
+Siga `.aiignore` antes de abrir relatorios gerados.
+
+Este protocolo e obrigatorio para tarefas tecnicas neste projeto. Antes de
+editar, classifique risco, escolha rota e valide a entrega.
+
+## Ordem de leitura
+
+1. `protocol/fast-path.yaml`
+2. `protocol/router.yaml`
+3. Arquivo YAML especifico em `protocol/` conforme a rota.
+
+## Regras de execucao
+
+- Classifique o risco antes de agir.
+- Use o menor contexto suficiente.
+- Leia apenas os arquivos indicados por `protocol/router.yaml`.
+- Quando houver contexto grande, historico longo ou risco de confusao, use
+  `protocol/context-compiler.yaml` antes de abrir muitos arquivos.
+- Use `protocol/spec-driven.yaml` para feature, refatoracao grande ou tarefa
+  critica, sem criar spec pesada para tarefa simples.
+- Sempre entregue `Prompt original` e `Prompt melhorado da IA`; em baixo risco,
+  prefira micro formato legivel com `PO`, `PM` e `OK`.
+- Nao edite arquivo que nao foi identificado como candidato.
+- Preserve documentos, regras de IDE e configuracoes de framework existentes,
+  salvo pedido explicito do usuario.
+- Se o risco subir, atualize a classificacao antes de continuar.
+- Para nivel critico, peca confirmacao antes de acao sensivel.
+- Quando houver risco de quebrar fluxo existente, entregue uma lista do que
+  testar.
+- Entregue com evidencia em poucas linhas: mudanca, validacao, limite e risco
+  residual.
+- Explique o resultado em linguagem clara para uma pessoa leiga entender.
+
+## Convivencia com arquivos existentes
+
+Quando houver conflito, siga esta prioridade:
+
+1. pedido atual do usuario;
+2. este bloco obrigatorio em `AGENTS.md`;
+3. regras especificas da IDE ou do projeto;
+4. docs e historico somente quando a rota pedir.
+
+Nao sobrescreva `README.md`, `docs/`, `.cursorrules`, `CLAUDE.md`,
+`.github/copilot-instructions.md` ou configs de framework sem pedido claro.
+
+## Regras de organizacao
+
+- Nenhum arquivo deve passar de 400 linhas.
+- Organize primeiro para legibilidade por IA.
+- Use YAML para regras operacionais.
+- Evite duplicar a mesma regra em muitos lugares.
+
+<!-- AI_PROTOCOL_END -->
+"""
+
+
+def protocol_block() -> str:
+    text = minimal_agents()
+    start = text.index(MARKER_START)
+    end = text.index(MARKER_END) + len(MARKER_END)
+    return text[start:end]
+
+
+def backup_path(path: Path, backup_root: Path) -> None:
+    if not path.exists():
+        return
+    backup_root.mkdir(parents=True, exist_ok=True)
+    destination = backup_root / path.name
+    if path.is_dir():
+        shutil.copytree(path, destination)
+    else:
+        shutil.copy2(path, destination)
+
+
+def copy_protocol(target: Path, force: bool, backup_root: Path) -> None:
+    if target.exists() and not force:
+        return
+    if target.exists():
+        backup_path(target, backup_root)
+        shutil.rmtree(target)
+    target.mkdir(parents=True, exist_ok=True)
+    source = protocol_source()
+    for name in REQUIRED_PROTOCOL_FILES:
+        (target / name).write_text(source.joinpath(name).read_text(encoding="utf-8"), encoding="utf-8")
+
+
+def install_agents(target: Path) -> None:
+    block = protocol_block()
+    if not target.exists():
+        target.write_text(minimal_agents(), encoding="utf-8")
+        return
+
+    text = target.read_text(encoding="utf-8")
+    if MARKER_START in text and MARKER_END in text:
+        before, rest = text.split(MARKER_START, 1)
+        _, after = rest.split(MARKER_END, 1)
+        merged = before.rstrip() + "\n\n" + block + after
+    else:
+        merged = block + "\n\n## Instrucoes existentes do projeto\n\n" + text
+    target.write_text(merged.strip() + "\n", encoding="utf-8")
+
+
+def install_aiignore(target: Path) -> None:
+    existing = target.read_text(encoding="utf-8").splitlines() if target.exists() else []
+    lines = list(existing)
+    for item in AIIGNORE_LINES:
+        if item not in lines:
+            lines.append(item)
+    target.write_text("\n".join(lines).strip() + "\n", encoding="utf-8")
+
+
+def print_dry_run(target_root: Path, force: bool) -> None:
+    print(f"DRY-RUN target -> {target_root.resolve()}")
+    print(("update" if (target_root / "AGENTS.md").exists() else "create") + ":AGENTS.md")
+    print(("update" if (target_root / ".aiignore").exists() else "create") + ":.aiignore")
+    protocol_dir = target_root / "protocol"
+    if protocol_dir.exists() and force:
+        print("backup:protocol/")
+        print("replace:protocol/")
+    elif protocol_dir.exists():
+        print("keep:protocol/")
+    else:
+        print("create:protocol/")
+
+
+def install(target: str, force: bool, dry_run: bool = False) -> int:
+    target_root = Path(target).resolve()
+    if dry_run:
+        print_dry_run(target_root, force)
+        return 0
+
+    target_root.mkdir(parents=True, exist_ok=True)
+    backup_root = target_root / ".ai-protocol-backup" / datetime.now().strftime("%Y%m%d%H%M%S")
+
+    if (target_root / "AGENTS.md").exists():
+        backup_path(target_root / "AGENTS.md", backup_root)
+    if (target_root / ".aiignore").exists():
+        backup_path(target_root / ".aiignore", backup_root)
+
+    install_agents(target_root / "AGENTS.md")
+    install_aiignore(target_root / ".aiignore")
+    copy_protocol(target_root / "protocol", force, backup_root)
+
+    print(f"installed protocol -> {target_root}")
+    return verify(target)
+
+
+def verify(target: str) -> int:
+    root = Path(target).resolve()
+    errors: list[str] = []
+
+    for item in REQUIRED_FILES:
+        path = root / item
+        if not path.exists():
+            errors.append(f"missing:{item}")
+            continue
+        if path.is_file() and len(path.read_text(encoding="utf-8").splitlines()) > 400:
+            errors.append(f"line_limit:{item}")
+
+    for item, snippets in REQUIRED_TEXT.items():
+        path = root / item
+        if not path.exists() or not path.is_file():
+            continue
+        text = path.read_text(encoding="utf-8")
+        for snippet in snippets:
+            if snippet not in text:
+                errors.append(f"missing_text:{item}:{snippet}")
+
+    if errors:
+        print("FAIL")
+        for error in errors:
+            print(error)
+        return 1
+
+    print("PASS")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(prog="ai-protocol")
+    subparsers = parser.add_subparsers(dest="command")
+
+    install_parser = subparsers.add_parser("install", help="Install protocol into a project")
+    install_parser.add_argument("target", nargs="?", default=".", help="Project root")
+    install_parser.add_argument("--no-force", action="store_true", help="Do not replace existing protocol folder")
+    install_parser.add_argument("--dry-run", action="store_true", help="Show planned changes without writing files")
+
+    init_parser = subparsers.add_parser("init", help="Initialize protocol in a new project")
+    init_parser.add_argument("target", nargs="?", default=".", help="Project root")
+    init_parser.add_argument("--no-force", action="store_true", help="Do not replace existing protocol folder")
+    init_parser.add_argument("--dry-run", action="store_true", help="Show planned changes without writing files")
+
+    verify_parser = subparsers.add_parser("verify", help="Verify protocol installation")
+    verify_parser.add_argument("target", nargs="?", default=".", help="Project root")
+
+    args = parser.parse_args()
+    if args.command in {"install", "init"}:
+        return install(args.target, force=not args.no_force, dry_run=args.dry_run)
+    if args.command == "verify":
+        return verify(args.target)
+
+    parser.print_help()
+    return 1

ai_execution_protocol/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

ai_execution_protocol/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

ai_execution_protocol/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

ai_execution_protocol/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

ai_execution_protocol/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

ai_execution_protocol/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