cox-protocol-package 1.0.0

package/protocols/recursive_decomposition_protocol.cox

@@ -0,0 +1,96 @@
+CoxVersion: "1.0"
+FileType: "protocol_doc"
+Slug: "recursive_decomposition_protocol"
+Schema: "cox.protocol.v1"
+ProtocolName: "Recursive Decomposition Protocol"
+Purpose: "Decide when to keep a screenshot as one .cox file and when to split into component/subcomponent folders."
+
+Principle:
+  Statement: "Decompose only until each file is clear, named deterministically, and implementation-ready. Do not split for its own sake."
+
+ComplexityLevels:
+  SimplePage:
+    Criteria:
+      - "One dominant purpose"
+      - "One primary form, panel, or content region"
+      - "Few interactive states"
+      - "No major nested component ambiguity"
+    Action: "Create only {page_slug}.cox plus {page_slug}_screenshot."
+    Example: "Minimal sign-in page"
+  ModeratePage:
+    Criteria:
+      - "Two to five distinguishable components"
+      - "Components have clear names and boundaries"
+      - "Interactions are localized"
+    Action: "Create {page_slug}.cox plus component folders."
+  ComplexPage:
+    Criteria:
+      - "More than five components"
+      - "Dense dashboard, analytics, sidebar, grid, toolbar, charts, modals, or nested states"
+      - "Some components require creative implementation reasoning"
+    Action: "Create {page_slug}.cox, component folders, and subcomponent folders only where needed."
+
+DecompositionDecisionTree:
+  - Question: "Can the page be explained accurately in one {page_slug}.cox without becoming long or ambiguous?"
+    Yes: "Do not split."
+    No: "Identify primary components."
+  - Question: "Are component boundaries visually distinguishable?"
+    Yes: "Create component folders."
+    No: "Use {page_slug}.cox with internal regions and mark boundaries as Inferred."
+  - Question: "Would a component name need vague or overly specific wording to be unique?"
+    Yes: "Split or rename using purpose/domain; validate sibling names."
+    No: "Keep component as-is."
+  - Question: "Does the component contain multi-layered visual logic, expandable interactions, nested states, or creative animation?"
+    Yes: "Create ComplexSubcomponentName folders."
+    No: "Keep inside component .cox."
+
+PageCoxResponsibility:
+  Includes:
+    - "Page purpose"
+    - "Global layout grid"
+    - "Component map"
+    - "Responsive variants"
+    - "Page-level interactions"
+    - "Links to child component .cox files"
+  Excludes:
+    - "Deep per-component implementation details when child folder exists"
+
+ComponentCoxResponsibility:
+  Includes:
+    - "Component purpose"
+    - "Visible structure"
+    - "Styling tokens"
+    - "States and interactions"
+    - "Data bindings"
+    - "Implementation hints"
+    - "Links to subcomponent .cox files if present"
+
+ComplexSubcomponentCoxResponsibility:
+  IncludeOnlyWhen:
+    - "Subcomponent needs special creative reasoning"
+    - "Subcomponent has independent motion, states, interactions, data, or security/testing notes"
+    - "Component .cox would otherwise become ambiguous or too long"
+
+OverEngineeringGuardrails:
+  - "Do not create subcomponents for every button, icon, or text label."
+  - "Do not split a simple sign-in page unless user explicitly asks."
+  - "Do not split merely because visual elements exist; split because explanation or implementation benefits."
+  - "Prefer one clear component over many fragile micro-components."
+
+RecursiveFlow:
+  ConstructHierarchyFirst:
+    - "Project"
+    - "Pages"
+    - "Responsive page variants"
+    - "Components"
+    - "Complex subcomponents"
+  ThenWriteFiles:
+    - "Root docs"
+    - "{page_slug}.cox files"
+    - "Component .cox files"
+    - "Subcomponent .cox files"
+  ThenValidate:
+    - "Names"
+    - "Evidence levels"
+    - "File existence"
+    - "Zip contents"

package/protocols/screenshot_partitioning_protocol.cox

@@ -0,0 +1,64 @@
+CoxVersion: "1.0"
+FileType: "protocol_doc"
+Slug: "screenshot_partitioning_protocol"
+Schema: "cox.protocol.v1"
+ProtocolName: "Screenshot Partitioning Protocol"
+Purpose: "Define how agents estimate section containers, borders, and crops from screenshots."
+
+Inputs:
+  AcceptedFormats: ["png", "jpg", "jpeg", "webp"]
+  MinimumScreenshots: 1
+
+PartitioningRules:
+  - "Always preserve the original full-page screenshot at page level."
+  - "Create component screenshots only when the component boundary is sufficiently clear."
+  - "Use visual section containers, borders, spacing, background changes, alignment, and hierarchy to estimate crop boundaries."
+  - "Include slight padding around crops so shadows, glows, popovers, badges, and floating controls are not clipped."
+  - "If a border is unclear, keep the broader region and mark boundary confidence as Medium or Low."
+  - "Do not crop out contextual labels required to understand the component."
+  - "Do not invent hidden offscreen UI."
+
+BoundaryConfidence:
+  High:
+    Meaning: "Clear visual border, container, or region separation."
+    Action: "Crop component screenshot."
+  Medium:
+    Meaning: "Region is distinguishable by spacing/alignment, but edge is inferred."
+    Action: "Crop with padding and mark EstimatedBoundary."
+  Low:
+    Meaning: "Boundary is ambiguous or overlapping."
+    Action: "Avoid crop or use parent screenshot reference."
+
+CropMetadataRequired:
+  Fields:
+    - "SourceScreenshot"
+    - "OutputScreenshot"
+    - "BoundaryConfidence"
+    - "EstimatedBoundingBox"
+    - "IncludedPaddingReason"
+    - "ExcludedRegions"
+
+EstimatedBoundingBoxFormat:
+  Units: "pixels when known, percentage when exact pixel coordinates are not available"
+  Examples:
+    Pixel: "x:0 y:0 width:280 height:900"
+    Percent: "x:0% y:0% width:22% height:100%"
+
+ResponsiveVariantHandling:
+  PageLevel:
+    Rule: "Desktop, tablet, and mobile variants stay in same Page folder when they represent the same page."
+  ComponentLevel:
+    Rule: "Component variant screenshots stay in the same component folder when they represent the same component."
+  Naming:
+    - "dashboard_screenshot_desktop.png"
+    - "dashboard_screenshot_tablet.png"
+    - "dashboard_screenshot_mobile.png"
+    - "{component_slug}_screenshot_desktop.png"
+    - "{component_slug}_screenshot_mobile.png"
+
+AgenticToolInstruction:
+  RequiredBehavior:
+    - "Use vision models to identify regions before cropping."
+    - "Use image tools to crop only after a region plan is written."
+    - "Verify generated crop files exist on disk."
+    - "Record all crops in manifest.cox."

package/protocols/sub_agents_orchestration.cox

@@ -0,0 +1,85 @@
+CoxVersion: "1.0"
+FileType: "protocol_doc"
+Slug: "sub_agents_orchestration"
+Schema: "cox.protocol.v1"
+ProtocolName: "Sub-Agents Orchestration"
+Purpose: "Divide COX package generation into expert sub-agent responsibilities."
+
+CoordinatorAgent:
+  Mission: "Own the full package contract, sequence sub-agents, and ensure final ZIP integrity."
+  Inputs: ["UserRequirements", "Screenshots", "ExistingArtifacts"]
+  Outputs: ["FinalZip", "manifest.cox", "VerificationReport"]
+  MustNot:
+    - "Claim files exist before checking disk."
+
+RequirementsAnalystAgent:
+  Mission: "Extract project purpose, pages, platform constraints, style requirements, and explicit user naming preferences."
+  Outputs:
+    - "requirements_summary.cox"
+    - "ProjectName proposal"
+    - "PageName proposals"
+
+VisionInspectorAgent:
+  Mission: "Inspect screenshots and identify page type, layout, visual hierarchy, components, responsive variants, and evidence levels."
+  Outputs:
+    - "visual_inventory.cox"
+    - "page_component_candidates"
+    - "boundary_confidence estimates"
+
+NamingArchitectAgent:
+  Mission: "Apply deterministic naming convention, reject ambiguous names, and produce final Project/Page/Component/Subcomponent names."
+  Outputs:
+    - "naming_decisions.cox"
+    - "RejectedAlternatives"
+    - "AmbiguityValidationPass"
+
+ScreenshotPartitionAgent:
+  Mission: "Create page-level and component-level screenshots using estimated containers and safe padding."
+  Outputs:
+    - "cropped component screenshots"
+    - "crop_metadata.cox"
+  Constraint: "Only crop when boundary confidence is High or Medium."
+
+CoxSpecWriterAgent:
+  Mission: "Write {page_slug}.cox, component .cox, and complex subcomponent .cox files."
+  Outputs:
+    - "{page_slug}.cox"
+    - "{component_slug}.cox"
+    - "{subcomponent_slug}.cox"
+
+LogicAndImplementationAgent:
+  Mission: "Write product logic, data flow, API routes, safe runtime controls, and coding-agent implementation plan."
+  Outputs:
+    - "protocols/website_logic_and_functionality.cox"
+    - "protocols/coding_agent_starting_point.cox"
+
+DesignSystemAgent:
+  Mission: "Extract reusable visual tokens and component relationships."
+  Outputs:
+    - "protocols/design_tokens.cox"
+    - "protocols/component_binding_graph.cox"
+
+ValidationAgent:
+  Mission: "Verify naming, evidence levels, file existence, UTF-8 text, screenshot/spec pairs, and zip contents."
+  Outputs:
+    - "manifest.cox"
+    - "protocols/visual_acceptance_checklist.cox"
+    - "zip_content_listing.txt"
+
+ExecutionOrder:
+  - "CoordinatorAgent"
+  - "RequirementsAnalystAgent"
+  - "VisionInspectorAgent"
+  - "NamingArchitectAgent"
+  - "ScreenshotPartitionAgent"
+  - "DesignSystemAgent"
+  - "CoxSpecWriterAgent"
+  - "LogicAndImplementationAgent"
+  - "ValidationAgent"
+  - "CoordinatorAgent final zip assembly"
+
+EscalationRules:
+  - "If naming ambiguity persists, split component or choose purpose-based name."
+  - "If boundary confidence is Low, do not crop; reference parent screenshot."
+  - "If a feature is not visible, mark as Inferred, Intended, or Recommended."
+  - "If a file is missing, do not include it in manifest as completed."

package/protocols/visual_acceptance_checklist.cox

@@ -0,0 +1,30 @@
+CoxVersion: "1.0"
+FileType: "protocol_doc"
+Slug: "visual_acceptance_checklist"
+Schema: "cox.protocol.v1"
+ProtocolName: "Visual Acceptance Checklist"
+Purpose: "Give implementation agents concrete pass/fail checks for reconstructed UI."
+
+GlobalChecks:
+  - "All page and component names match protocols/deterministic_naming_convention.cox."
+  - "Each page folder contains {page_slug}.cox and at least one {page_slug}_screenshot file."
+  - "Each component folder contains component_slug.cox and component_slug_screenshot if a crop was generated."
+  - "Evidence levels are present for visible, inferred, intended, and recommended behavior."
+
+VisualChecks:
+  - "Glass surfaces use translucent cards, subtle border, and soft shadow."
+  - "Typography uses compact bold headings, readable body text, and muted metadata."
+  - "Card grids preserve spacing, radius, preview area, metadata density, and status badges."
+  - "Sidebar/header/analytics regions remain visually distinguishable."
+  - "Responsive layout degrades predictably from desktop to tablet to mobile."
+
+InteractionChecks:
+  - "Hover states are subtle and native-feeling."
+  - "Active/selected states use primary accent without overwhelming layout."
+  - "Loading, empty, error, and unhealthy states are implemented where specified."
+  - "Runtime actions are guarded by safe confirmations where required."
+
+NamingChecks:
+  - "No timestamp-named screenshots remain in final folders unless intentionally preserved as source references."
+  - "No sibling names are near-duplicates like left_sidebar and left_navigation."
+  - "Names are neither vague nor over-specific."

package/protocols/website_logic_and_functionality.cox

@@ -0,0 +1,82 @@
+CoxVersion: "1.0"
+FileType: "protocol_doc"
+Slug: "website_logic_and_functionality"
+Schema: "cox.protocol.v1"
+ProtocolName: "Website Logic And Functionality"
+Purpose: "Capture the product logic, state transitions, data model, and safety notes behind the COX sample application."
+
+ProductPurpose:
+  Evidence: UserSpecified
+  Summary: "LocalAppManager helps users browse, monitor, launch, and inspect local projects/apps from a visual dashboard."
+
+CoreEntities:
+  Project:
+    Evidence: Inferred
+    Fields: ["id", "name", "path", "status", "port", "tags", "favorite", "lastOpened", "previewImage", "runtimeCommand"]
+  RuntimeStatus:
+    Evidence: UserSpecified
+    States: ["running", "stopped", "paused", "unhealthy", "indexing", "missing", "archived"]
+  AIProviderUsage:
+    Evidence: UserSpecified
+    MaxProviders: 10
+    Fields: ["provider", "requests", "tokens", "cost", "percentage"]
+
+FrontendResponsibilities:
+  Evidence: Inferred
+  Items:
+    - "Render project grid/list and page shell."
+    - "Filter, sort, tag, and favorite projects."
+    - "Display runtime status, health, previews, analytics, and empty/error states."
+    - "Send safe runtime commands through backend abstractions."
+
+BackendResponsibilities:
+  Evidence: Inferred
+  Items:
+    - "Scan configured local folders for projects."
+    - "Manage safe start/stop/restart operations."
+    - "Track ports, process health, and availability."
+    - "Generate/cache/refresh screenshots and previews."
+    - "Persist project metadata and user preferences."
+
+StateTransitions:
+  Evidence: UserSpecified
+  Allowed:
+    stopped: ["running", "missing", "archived", "indexing"]
+    running: ["paused", "stopped", "unhealthy", "archived"]
+    paused: ["running", "stopped"]
+    unhealthy: ["running", "stopped", "missing"]
+    indexing: ["running", "stopped", "missing"]
+    missing: ["indexing", "archived"]
+    archived: ["indexing"]
+
+ScreenshotsAndPreviews:
+  Evidence: UserSpecified
+  Behavior:
+    Generate: "Capture project preview when project is reachable."
+    Cache: "Store preview image with project metadata."
+    Refresh: "Refresh manually or after detected project activity."
+    Failure: "Use empty preview state if capture fails."
+
+FilteringSortingTagsFavorites:
+  Evidence: UserSpecified
+  Behavior:
+    Filters: ["status", "tag", "favorite", "runtime", "recent"]
+    Sorting: ["last opened", "name", "status", "activity", "port"]
+    Tags: "User-defined labels for grouping projects."
+    Favorites: "Pinned/high-priority projects displayed first or filterable."
+
+PersistenceModel:
+  Evidence: Inferred
+  RecommendedStorage:
+    LocalConfig: "project paths, preferences, ignored folders"
+    LocalDatabase: "project metadata, runtime history, preview paths, AI usage summaries"
+    CacheFolder: "generated screenshots and thumbnails"
+
+SecurityAndPrivacyNotes:
+  Evidence: Recommended
+  Notes:
+    - "Avoid destructive file operations without explicit user confirmation."
+    - "Never expose secrets found in project folders."
+    - "Sandbox runtime commands where possible."
+    - "Show clear confirmation before deleting, moving, or overwriting files."
+    - "Treat local paths and usage metrics as private user data."

package/pyproject.toml

@@ -0,0 +1,51 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "cox-protocol-package"
+version = "1.0.0"
+description = "Validator and compiler for COX design-spec documents"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+authors = [
+  { name = "Charbel Malo" },
+]
+keywords = [
+  "agent-protocol",
+  "cox",
+  "design-spec",
+  "schema",
+  "ui-reconstruction",
+  "yaml",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Topic :: Software Development :: Build Tools",
+  "Topic :: Text Processing :: Markup",
+]
+dependencies = [
+  "PyYAML>=6.0",
+  "jsonschema>=4.23",
+  "typer>=0.12",
+  "rich>=13.7",
+]
+
+[project.scripts]
+cox = "tools.cox_cli:app"
+
+[project.urls]
+Homepage = "https://github.com/charbelmalo/cox-protocol-package#readme"
+Repository = "https://github.com/charbelmalo/cox-protocol-package"
+Issues = "https://github.com/charbelmalo/cox-protocol-package/issues"
+
+[tool.setuptools]
+packages = ["tools"]

package/requirements.txt

@@ -0,0 +1,4 @@
+PyYAML>=6.0
+jsonschema>=4.23
+typer>=0.12
+rich>=13.7

package/schemas/cox.component.v1.schema.json

@@ -0,0 +1,167 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "cox.component.v1",
+  "title": "COX Component Spec",
+  "type": "object",
+  "required": [
+    "CoxVersion",
+    "FileType",
+    "ComponentName",
+    "Slug",
+    "Schema",
+    "Role",
+    "EvidenceSummary",
+    "VisibleStructure",
+    "Interactions",
+    "NamingDecision"
+  ],
+  "properties": {
+    "CoxVersion": {
+      "const": "1.0"
+    },
+    "FileType": {
+      "const": "component_spec"
+    },
+    "ComponentName": {
+      "type": "string",
+      "minLength": 1
+    },
+    "Slug": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(_[a-z0-9]+)*$"
+    },
+    "Schema": {
+      "const": "cox.component.v1"
+    },
+    "Role": {
+      "type": "string"
+    },
+    "EvidenceSummary": {
+      "$ref": "#/$defs/evidenceSummary"
+    },
+    "VisibleStructure": {
+      "type": "object"
+    },
+    "Interactions": {
+      "$ref": "#/$defs/interactionSummary"
+    },
+    "NamingDecision": {
+      "$ref": "#/$defs/namingDecision"
+    },
+    "VisualStyle": {
+      "type": "object"
+    },
+    "Responsive": {
+      "type": "object"
+    },
+    "ImplementationHints": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "ChildSubcomponents": {
+      "type": "array"
+    }
+  },
+  "$defs": {
+    "evidenceSummary": {
+      "type": "object",
+      "properties": {
+        "Visible": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "UserSpecified": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "Inferred": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "Intended": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "Recommended": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": true
+    },
+    "interactionSummary": {
+      "type": "object",
+      "properties": {
+        "Visible": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "Inferred": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "Intended": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "Recommended": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": true
+    },
+    "namingDecision": {
+      "type": "object",
+      "required": [
+        "ChosenName",
+        "Reason",
+        "RejectedAlternatives",
+        "AmbiguityRisk",
+        "EvidenceLevel"
+      ],
+      "properties": {
+        "ChosenName": {
+          "type": "string"
+        },
+        "Reason": {
+          "type": "string"
+        },
+        "RejectedAlternatives": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "AmbiguityRisk": {
+          "type": "string"
+        },
+        "EvidenceLevel": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": true
+    }
+  },
+  "additionalProperties": true
+}

package/schemas/cox.crop_metadata.v1.schema.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "cox.crop_metadata.v1",
+  "title": "COX Crop Metadata",
+  "type": "object",
+  "required": [
+    "CoxVersion",
+    "FileType",
+    "Slug",
+    "Schema",
+    "SourceScreenshot",
+    "OutputScreenshot",
+    "BoundaryConfidence",
+    "EstimatedBoundingBox"
+  ],
+  "properties": {
+    "CoxVersion": {
+      "const": "1.0"
+    },
+    "FileType": {
+      "const": "crop_metadata"
+    },
+    "Slug": {
+      "type": "string",
+      "pattern": "^[a-z0-9]+(_[a-z0-9]+)*$"
+    },
+    "Schema": {
+      "const": "cox.crop_metadata.v1"
+    },
+    "SourceScreenshot": {
+      "type": "string"
+    },
+    "OutputScreenshot": {
+      "type": "string"
+    },
+    "BoundaryConfidence": {
+      "type": "string",
+      "enum": [
+        "High",
+        "Medium",
+        "Low"
+      ]
+    },
+    "EstimatedBoundingBox": {
+      "type": "object",
+      "required": [
+        "Unit",
+        "X",
+        "Y",
+        "Width",
+        "Height"
+      ],
+      "properties": {
+        "Unit": {
+          "type": "string"
+        },
+        "X": {
+          "type": "string"
+        },
+        "Y": {
+          "type": "string"
+        },
+        "Width": {
+          "type": "string"
+        },
+        "Height": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": true
+    },
+    "IncludedPaddingReason": {
+      "type": "string"
+    },
+    "ExcludedRegions": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "additionalProperties": true
+}