{"owner":"a2ui-project","repo":"a2ui","hasSkills":true,"totalSkillsCount":96,"totalTokensCount":44130,"categories":["anthropic-skill","root-instruction","gemini-rule","project-spec","plugin-manifest","subagent-persona"],"hasMcp":false,"mcpConfig":null,"found":[".agents/skills/a2ui-doc-sync-check/SKILL.md",".agents/skills/a2ui-audit/SKILL.md",".agents/skills/a2ui-implement-new-sdks-for-client-language/SKILL.md",".agents/skills/a2ui-issue-triage/SKILL.md",".agents/skills/a2ui-generate-pydantic-models/SKILL.md",".agents/skills/a2ui-add-eval-datapoint/SKILL.md",".agents/skills/a2ui-release-python/SKILL.md",".agents/skills/a2ui-test-quality-check/SKILL.md",".agents/skills/a2ui-remediate-problem/SKILL.md",".agents/skills/natural-writing/SKILL.md",".agents/skills/inspect-ai/SKILL.md",".agents/skills/coding-principles/SKILL.md",".agents/skills/pr-hygiene/SKILL.md",".agents/skills/update-changelog/SKILL.md","blueprints/skills/a2ui-blueprint-compliance/SKILL.md","blueprints/skills/a2ui-blueprint-maintenance/SKILL.md","blueprints/skills/a2ui-blueprint-navigator/SKILL.md","blueprints/skills/a2ui-create-feature-blueprint/SKILL.md","blueprints/skills/a2ui-implement-feature-from-blueprint/SKILL.md","conformance/test_data/skills/express_basic_catalog.skill.md","conformance/test_data/skills/express_basic_monolithic.skill.md","conformance/test_data/skills/express_core.skill.md","conformance/test_data/skills/fake_monolithic.skill.md","eval/iterative_format_optimizer/skills/inference-format-optimizer/SKILL.md","AGENTS.md",".gemini/GEMINI.md","eval/DESIGN.md","swift/AGENTS.md","tools/build_catalog/README.md","tools/composer/AGENTS.md","tools/composer/README.md","tools/composer/components.json","tools/composer/package.json","tools/composer/tsconfig.json","tools/editor/README.md","tools/editor/package.json","tools/editor/tsconfig.json","tools/inspector/README.md","tools/inspector/package.json","tools/inspector/tsconfig.json",".agents/skills/a2ui-issue-triage/README.md","conformance/extensions/a2a/a2a_integration.yaml","conformance/extensions/adk/adk_extensions.yaml","typescript/agents/a2ui_agent/CHANGELOG.md","typescript/agents/a2ui_agent/KNOWN_GAPS.md","typescript/agents/a2ui_agent/README.md","typescript/agents/a2ui_agent/package.json","typescript/agents/a2ui_agent/tsconfig.check.json","typescript/agents/a2ui_agent/tsconfig.json",".agents/skills/a2ui-audit/references/gh-reference.md",".agents/skills/a2ui-issue-triage/references/triage_criteria.md",".agents/skills/a2ui-remediate-problem/references/pr-description-template.md",".agents/skills/coding-principles/subskills/public-api-and-cross-framework-design.md","tools/build_catalog/tests/fixtures/basic_catalog.json","tools/build_catalog/tests/fixtures/common_types.json","tools/build_catalog/tests/fixtures/component1.json","tools/build_catalog/tests/fixtures/component2.json","tools/build_catalog/tests/fixtures/component3.json","tools/build_catalog/tests/fixtures/v0_8_custom_catalog.json","tools/build_catalog/tests/fixtures/v0_8_standard_catalog_definition.json",".agents/skills/coding-principles/subskills/dart/INDEX.md",".agents/skills/coding-principles/subskills/dart/versioning-and-releases.md",".agents/skills/coding-principles/subskills/python/INDEX.md",".agents/skills/coding-principles/subskills/python/architecture-and-facades.md",".agents/skills/coding-principles/subskills/python/coding-standards-and-verification.md",".agents/skills/coding-principles/subskills/swift/INDEX.md",".agents/skills/coding-principles/subskills/swift/coding-standards-and-testing.md",".agents/skills/coding-principles/subskills/typescript/INDEX.md",".agents/skills/coding-principles/subskills/typescript/accessibility-semantics.md",".agents/skills/coding-principles/subskills/typescript/css-theming-styling.md",".agents/skills/coding-principles/subskills/typescript/reactive-lifecycle-performance.md",".agents/skills/coding-principles/subskills/typescript/testing-isolation.md",".agents/skills/coding-principles/subskills/typescript/typescript-closure-compiler.md","blueprints/codebases/typescript/agents/a2ui_agent/codebase.blueprint.md","eval/iterative_format_optimizer/skills/inference-format-optimizer/references/agent_instructions.md","eval/iterative_format_optimizer/skills/inference-format-optimizer/references/inference_format_iteration.md","eval/iterative_format_optimizer/skills/inference-format-optimizer/references/scoring_model.md","eval/iterative_format_optimizer/skills/inference-format-optimizer/references/subagent_protocol.md","eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/README.md","eval/iterative_format_optimizer/skills/inference-format-optimizer/templates/subagent_prompt.md","specification/v1_0/extensions/a2a/docs/a2ui_extension_specification.md","tools/composer/src/data/theater/booking-form.json","tools/composer/src/data/theater/component-gallery-stream.json","tools/composer/src/data/theater/contact-card.json","tools/composer/src/data/theater/flight-status.json","tools/composer/src/data/theater/floor-plan.json","tools/composer/src/data/theater/kitchen-sink.json","tools/composer/src/data/theater/northstar-tour.json","tools/composer/src/data/theater/org-chart.json","tools/composer/src/data/theater/restaurant-booking.json","tools/composer/src/data/theater/restaurant-confirmation.json","tools/composer/src/data/theater/restaurant-finder.json","tools/composer/src/data/theater/restaurant-grid.json","tools/composer/src/data/theater/rizzcharts-chart.json","tools/composer/src/data/theater/weather-widget.json",".agents/skills/coding-principles/subskills/typescript/references/inspecting-typescript-public-api.md"],"skills":{".agents/skills/a2ui-doc-sync-check/SKILL.md":"---\nname: a2ui-doc-sync-check\ndescription: Auditing codebase implementations for synchronization drift with the user documentation, readmes, and code comments.\n---\n\n# A2UI Code and Documentation Synchronization Check Skill\n\nThis skill guides the process of auditing concrete codebase implementations to verify that they are synchronized with their respective documentation files, codebase READMEs, and inline code comments/docstrings.\n\n---\n\n## **Instructions**\n\n1. **Locate Documentation and Readmes**:\n - Find all user guides, tutorials, and specifications under `docs/` and `specification/`.\n - Find the `README.md` files in each codebase directory.\n\n2. **Audit Readme Commands and Configs**:\n - For each codebase directory, parse the `README.md` to extract setup commands, dependencies, build/test commands, and directory layouts.\n - Cross-reference these details with the codebase's project files (e.g. `package.json`, `pyproject.toml`, `pubspec.yaml`, `Package.swift`).\n - If any command listed in the readme is invalid, deprecated, or has wrong arguments, list it as a discrepancy.\n\n3. **Audit Code-vs-Docs Public API and Settings**:\n - Make sure the glossary is respected. Verify that terms used in code, documentation and blueprints are consistent with [the glossary](../../../docs/public/concepts/glossary.md). If you find deviations, suggest fixes. If you see an important term is used in documentation and/or API, but is missing from the glossary, suggest an update for the glossary.\n - Inspect the codebase's public API entrypoints (classes, interfaces, types, methods).\n - Compare them against any descriptions, structural maps, or code snippets in the `docs/` folder.\n - Look for renamed classes, changed signatures, or removed options that are still described in the docs.\n - If the codebase exposes new settings or flags that are undocumented in `docs/` or the spec guides, log them as missing documentation.\n\n4. **Audit Inline Comments and Docstrings**:\n - Audit inline comments and docstrings (e.g. JSDoc in TS, docstrings in Python, triple-slash comments in Dart/Swift) for public APIs.\n - Flag any mismatch where code parameter names, types, return behaviors, or exceptions thrown deviate from what the docstring claims.\n\n5. **Links and Duplicates**:\n - When an artifact (code, document, issue, PR, comment and so on) is referenced, make sure it has a link.\n - When a glossary term is used - link the first occurrence of the term to the glossary entry if it exists.\n - Make sure there is no duplications of content. If you find some, delete the duplicate and leave a reference.\n\n6. **Conciseness and Clarity**:\n - Verify that documentation and code comments follow the [natural-writing](../natural-writing/SKILL.md) skill, and flag text that breaks its rules.\n\n7. **Format the Report**:\n - Build a Markdown report summarizing the findings:\n - Table of audited directories.\n - **Documentation Drift**: Mismatches between documentation guides (`docs/`) and codebase implementations.\n - **Readme Errors**: Invalid setup, compile, or test commands found in `README.md` files.\n - **Docstring Mismatches**: Outdated parameter names or behaviors described in inline comments.\n - Return this Markdown report as your final response.\n",".agents/skills/a2ui-audit/SKILL.md":"---\nname: a2ui-audit\ndescription: Main coordination skill to run the blueprint compliance, documentation synchronization, and test quality audits, posting the combined results as a labeled GitHub issue.\n---\n\n# A2UI Compliance Verification Skill\n\nThis skill coordinates the execution of specification compliance, documentation\nsync, and test quality audits, and publishes the combined results as a GitHub issue.\n\nOther than writing a report and creating an issue, this skill is purely a\nread-only skill; no changes are to be made to the codebase. Do not attempt to\nfix issues.\n\n---\n\n## **Instructions**\n\n1. **Audit Codebase Blueprint Compliance**:\n - Execute `python3 blueprints/skills/a2ui-blueprint-compliance/scripts/check_compliance.py` to dynamically discover all 8 production codebases and generate the baseline Markdown status report.\n - Run the sub-skill [`a2ui-blueprint-compliance`](../../../blueprints/skills/a2ui-blueprint-compliance/SKILL.md) to audit each discovered codebase for missing features or blueprint drift.\n - Save the compiled Markdown report to a temporary file in the workspace (e.g., `compliance_report.md`) under the header `## Codebase Blueprint Compliance Audit`.\n\n2. **Audit Code vs. Documentation Synchronization**:\n - Run the sub-skill [`a2ui-doc-sync-check`](../a2ui-doc-sync-check/SKILL.md) to audit documentation drift across `docs/`, `specification/`, codebase READMEs, and inline docstrings.\n - Append the returned Markdown report to `compliance_report.md` under a new header `## Code & Documentation Sync Audit`.\n\n3. **Audit Test Quality & Assertion Strength**:\n - Run the sub-skill [`a2ui-test-quality-check`](../a2ui-test-quality-check/SKILL.md) to audit test suites across all codebases for weak assertions and behavioral verification.\n - Append the returned Markdown report to `compliance_report.md` under a new header `## Test Quality & Assertions Audit`.\n\n4. **Summarize the report**:\n - Add a `## Summary` section at the top of the `compliance_report.md` file with a detailed overview of the audit scope and key findings across all audited codebases.\n - Add a `## Recommendations` section listing actionable, prioritized follow-up items formatted as a numbered list (e.g. `1. **P0**: ...`). Each numbered item MUST represent a concrete, self-contained remediation task.\n - Immediately below the recommendations list, include the mandatory automated remediation callout:\n > 🤖 **Automated Remediation**: Comment `/fix ` (e.g., `/fix 1`) on this issue to have an agent create a draft PR for that recommendation.\n\n5. **Format and Detail Requirements**:\n - **MANDATORY COMPLETE REPOSITORY COVERAGE**: The report MUST include status rows and detailed findings for **ALL 8 production codebases** discovered by `check_compliance.py`. Do NOT truncate, shortcut, or abbreviate the summary tables or detailed findings.\n - For each audit section, provide specific evidence:\n - Exact file paths (e.g. `python/a2ui_agent/transport.py:L45-L60`).\n - Specific function/class names, parameter mismatches, or missing feature descriptions.\n - Concrete examples of weak assertions (e.g. `assert response is not None` in `eval/tests/test_strategies.py`).\n - Follow the structure provided in the **Report Format Template** below.\n\n6. **Publish Report**:\n - Execute the local Python helper script to create the GitHub issue containing the combined reports:\n ```bash\n python3 .agents/skills/a2ui-audit/scripts/create_compliance_report.py compliance_report.md --repo a2ui-project/a2ui\n ```\n - The publishing script will create the GitHub issue, automatically inject copyable remediation prompt blocks referencing the newly created issue URL under each recommendation item, and update the issue body.\n - Ensure the helper script runs successfully.\n - Clean up the temporary file `compliance_report.md` after completion.\n\n---\n\n## **Report Format Template**\n\nWhen compiling `compliance_report.md`, use the following structure:\n\n```markdown\n## Summary\n\n[Provide a 2-3 paragraph detailed summary explaining the repository state, key areas audited across SDKs, renderers, and tests, and major findings.]\n\n## Recommendations\n\n1. **[Priority]**: **[Title]**\n - [Clear detailed explanation of the fix needed, specifying affected directories or modules.]\n\n2. **[Priority]**: **[Title]**\n - [Clear detailed explanation of the fix needed, specifying affected directories or modules.]\n\n## Codebase Blueprint Compliance Audit\n\n| Codebase Implementation | Associated Module | Status | Commits Behind | Current Commit | Latest Commit |\n| ----------------------- | ------------------- | ------ | -------------- | -------------- | ------------- |\n| `path/to/codebase` | `associated_module` | Status | X | `commit_hash` | `latest_hash` |\n\n### Detailed Findings & Discrepancies\n\n- **[Codebase Path]**: [Detailed description of missing specifications, missing required features, or frontmatter commit hash drift.]\n\n## Code & Documentation Sync Audit\n\n| Directory | Status | Identified Issues |\n| ------------- | ------ | ----------------- |\n| `path/to/dir` | Status | Brief Summary |\n\n### Detailed Findings\n\n- **README Mismatches**:\n - `path/to/README.md`: [Exact invalid command or outdated setup step found in README.]\n- **Docstring / API Drift**:\n - `path/to/file.ext:L12-L34`: [Specific parameter or return type mismatch between implementation and docstring/comments.]\n\n## Test Quality & Assertions Audit\n\n| Suite / Module | Status | Observations |\n| --------------- | ------ | ------------- |\n| `path/to/tests` | Status | Brief Summary |\n\n### Detailed Findings\n\n- **Weak Assertions**:\n - `path/to/test_file.ext` (`test_function_name`): [Explanation of weak assertion, e.g. using `assertNotNull` instead of schema/type check.]\n- **Missing Edge Case Tests**:\n - `path/to/module`: [Boundary conditions, error cases, or invalid inputs that lack test coverage.]\n```\n\n---\n\n## **References**\n\n- Refer to the [`a2ui-blueprint-compliance`](../../../blueprints/skills/a2ui-blueprint-compliance/SKILL.md) skill for codebase blueprint checking.\n- Refer to the [`a2ui-doc-sync-check`](../a2ui-doc-sync-check/SKILL.md) skill for documentation sync checking.\n- Refer to the [`a2ui-test-quality-check`](../a2ui-test-quality-check/SKILL.md) skill for test quality and assertion checking.\n- Refer to the [`gh-reference`](./references/gh-reference.md) reference for GitHub CLI (`gh`) operations.\n",".agents/skills/a2ui-implement-new-sdks-for-client-language/SKILL.md":"---\nname: a2ui-implement-new-sdks-for-client-language\ndescription: Step-by-step phased instructions for building new A2UI Core SDKs, Framework Adapters, and Inference SDKs from scratch in any client language.\n---\n\n# A2UI SDK Implementation Guide (Phased Execution)\n\nThis skill provides expert instructions and sequences for AI agents or contributors tasked with implementing A2UI Core SDKs, Framework Adapters, or Agent/Inference SDKs in a new programming language or UI framework.\n\n---\n\n## **1. Core State SDK Phases**\n\nIf you are building a new **Core SDK** (e.g., in Rust, Swift, Go, or C++), you must follow this sequence of phases:\n\n### **Phase 1: Context & Schemas Ingestion**\n\nThoroughly review:\n\n- `blueprints/modules/a2ui_core.blueprint.md` (for state and message structures).\n- `specification/v1_0/json/common_types.json` (dynamic binding schemas).\n- `specification/v1_0/json/server_to_client.json` (message envelopes).\n- `catalogs/basic/v1/catalog.json` (target components catalog).\n\n### **Phase 2: Technical Architecture Planning**\n\nCreate a detailed, local architectural proposal detailing:\n\n- **Dependencies**: Which Schema library and Observable/Reactive library will you use? Note that the reactive library must support both discrete event subscription and stateful, signal-like data streams (e.g., BehaviorSubject/Signal).\n- **Component APIs**: How will you define the `ComponentApi` interface in this language?\n- **Binding Strategy**: How will you structure the abstract Core Binder Layer?\n- _STOP and obtain human reviewer approval on this plan before writing code._\n\n### **Phase 3: Core Model Layer**\n\nImplement the framework-agnostic data and processor layers:\n\n1. **Observables & Signals**: Implement multi-cast reactive streams with clear unsubscribe mechanism to prevent leaks.\n2. **Protocol Structures**: Create strictly-typed native classes/structs representing `A2uiMessage` envelopes and client capabilities with serialization/deserialization.\n3. **DataModel & JSON Pointers**: Implement relative/absolute path resolution, auto-vivification (auto-typing intermediate segments), and bubble/cascade path change notifications.\n4. **Core State Models**: Implement `ComponentModel`, `SurfaceComponentsModel`, `SurfaceModel`, and `SurfaceGroupModel`.\n5. **Context Mapping**: Implement `DataContext` and `ComponentContext`.\n6. **MessageProcessor**: Ingest incoming messages and mutate the state models. Generate `inlineCatalogs` client capabilities.\n7. **Verification**: Write comprehensive unit tests for pointer cascading, JSON deserialization/validation, and message dispatching.\n\n### **Phase 4: Foundational Basic Catalog Support**\n\nBootstrap support for the Basic Catalog:\n\n- **Foundational Components**: Define the pure API schemas and Binders for: `Text`, `Row`, `Column`, `Button`, and `TextField`.\n- **Foundational Functions**: Implement `formatString` to interpret `${expression}` syntaxes, supporting recursive token evaluations and reactive coercion.\n- **Verification**: Ensure properties update reactively when underlying data paths emit notifications.\n\n### **Phase 5: Complete Basic Catalog Support**\n\n- **Full Components & Binders**: Define core binders for all other components in `basic/catalog.json`.\n- **Full Functions**: Implement remaining basic mathematical, logical, and array operations.\n- **Validation**: Ensure strict type coercion rules are satisfied and memory disposals work flawlessly.\n\n---\n\n## **2. Framework Adapter SDK Phases**\n\nIf you are building a new **UI Framework Adapter / Renderer** (e.g., in Flutter/Dart, SwiftUI, Jetpack Compose, Vue, or Svelte), follow this sequence:\n\n### **Phase 1: Ingestion & Core Integration**\n\nReview:\n\n- `blueprints/modules/a2ui_framework_adapter.blueprint.md` (View and rendering architecture).\n- `catalogs/basic/v1/basic_catalog_implementation_guide.md` (spacing, alignment, and typography specifications).\n\n### **Phase 2: Architectural Plan**\n\nDraft a plan specifying:\n\n- **Component Registry**: How components are dynamically resolved and instantiated.\n- **Surface Widget**: How the root canvas mounts and recurses through the layout tree starting at `root`.\n- **Observer/State Bridge**: Which Strategy (Direct, Predefined Binders, or Automated wrappers) will connect core signals to native views.\n- _STOP and obtain human reviewer approval on this plan._\n\n### **Phase 3: Adapter & Lifecycle Layer**\n\n- Implement `ComponentImplementation` base traits/classes.\n- Implement the framework-native `Surface` entrypoint widget.\n- Implement subscription management: lazy-subscribing only on mount, handling path stability updates, and strictly calling `dispose()` on unmount.\n\n### **Phase 4: Bootstrapping Basic Catalog Rendering**\n\n- Build native visual elements for: `Text`, `Row`, `Column`, `Button`, and `TextField`.\n- Bundle these elements into the first framework catalog adapter.\n- Verify reactive layout properties dynamically.\n\n### **Phase 5: Gallery Application Milestone**\n\nBuild the **Gallery App** as a testing playground with:\n\n- Left Column: Sample navigation.\n- Center Column: Surface preview, JSON message stream, and step-by-step interactive message stepper.\n- Right Column: Live data model inspect pane and action logger.\n- Load the 5 foundational verification examples: `00_simple-text.json`, `00_row-layout.json`, `00_complex-layout.json`, `00_interactive-button.json`, and `00_simple-login-form.json`.\n- _STOP and obtain human reviewer approval of the UI and visual rendering performance._\n\n### **Phase 6: Full Catalog Support**\n\n- Implement all remaining widgets (e.g. Card, Image, List, etc.) and validation traits like `Checkable`.\n- Update the Gallery App to support all official examples in `catalogs/basic/v1/examples/`.\n- Run visual parity and event action tests to verify correctness.\n",".agents/skills/a2ui-issue-triage/SKILL.md":"---\nname: a2ui-issue-triage\ndescription: Automates the triage of GitHub issues in the A2UI repository. Helps the oncall engineer by fetching untriaged issues, generating AI-suggested priorities, assignees, and responses, launching a local review dashboard, and bulk-applying approved decisions to GitHub. Use when tasked with triaging new GitHub issues or managing the repository backlog.\n---\n\n# A2UI GitHub Issue Triage Skill\n\nThis skill guides the process of fetching, analyzing, reviewing, and applying triage decisions to GitHub issues in the A2UI repository using a local interactive dashboard.\n\n> [!IMPORTANT]\n> **WRITING GUIDELINES**\n> When drafting replies, explanations, or any prose, refer to the [natural-writing](../natural-writing/SKILL.md) skill to ensure clarity, accuracy, and tone.\n\n---\n\n## Workflow\n\nFollow these steps to triage new or backlog issues:\n\n### Step 1: Fetch Untriaged Issues\n\nUse the fetch script to retrieve all open issues lacking a priority label (`P0`, `P1`, `P2`, `P3`, `P4`) in the A2UI repository.\n\n1. Run the fetch script to download the issues to a raw JSON file in your conversation-specific scratch directory:\n `python3 .agents/skills/a2ui-issue-triage/scripts/fetch_issues.py --repo \"a2ui-project/a2ui\" --output-file \"/brain//scratch/raw_issues.json\"`\n\n---\n\n### Step 2: Analyze and Suggest Triage\n\nProcess the raw issues and generate recommended triage fields based on the project's triage criteria.\n\n1. Read the triage criteria reference document: [triage_criteria.md](references/triage_criteria.md) and repository canonical templates: [triage-templates.md](../../../docs/contributing/triage-templates.md).\n2. For each issue in `raw_issues.json`, evaluate its description and comments to determine:\n - **Priority**: `P0` (Urgent), `P1` (High), `P2` (Medium), `P3` (Low), `P4` (Unplanned/Out of Scope), or `None`. `P0` and `P1` require assignees.\n - **Assignee**: Recommended owner based on the affected component or area.\n - **Action**: `investigate`, `assign_and_fix`, `needs_info`, `backlog`, `close_duplicate`, `close_invalid`, or `close_resolved`.\n - **Labels**: Applicable repository labels (e.g. `type: bug`, `component: lit renderer`, `status: first-line-handled`, `status: waiting-for-author-response`).\n - **Reply**: A polite, structured draft response addressing the author using canonical templates.\n3. If an issue is a potential duplicate, perform at most three targeted GitHub searches to find matching canonical issues before suggesting `close_duplicate`.\n4. **Natively Orchestrate Subagents**: Instead of running a Python script to spawn subagents (which can fail due to local workstation gRPC credential policies), the parent agent should natively orchestrate the parallel evaluations:\n - Load the first N issues (defaulting to 10, or as requested) from `raw_issues.json`.\n - Call the `invoke_subagent` tool in parallel for those issues. Prompt each subagent to analyze its assigned issue against the guidelines in [triage_criteria.md](references/triage_criteria.md) and return a structured JSON block containing `priority`, `action`, `labels`, and `reply`.\n - Once all subagents report back, compile their recommendations into the standard schema:\n - Map component labels to suggested assignees using git log history if necessary, and include a short sentence in `assignee_reason` explaining why they were chosen (e.g., \"Suggesting gspencer because they recently modified related code\").\n - Inject `total_issues_count` (preserving the total count from the raw issues JSON).\n - Save the final compiled payload to `issues_to_triage.json` in the scratch directory.\n\n---\n\n### Step 3: Launch Review Dashboard\n\nLaunch the interactive web dashboard to allow the oncall engineer to review and refine the suggested triages.\n\n1. Start the local server as a background task, pointing it to your scratch directory:\n `python3 .agents/skills/a2ui-issue-triage/scripts/launch_dashboard.py --data-file \"/brain//scratch/issues_to_triage.json\" --output-file \"/brain//scratch/triage_decisions.json\"`\n Set `WaitMsBeforeAsync` to `1000` so the server runs in the background.\n2. **Wait for Completion**: Stop calling tools and go idle. The launcher will automatically open the browser for the user and block until they click \"Apply Triages\" or \"Abort\". Once the user acts, the background task will complete, and you will receive a notification with the exit status.\n3. **Verify Exit Status**:\n - If the task exited with status `0` (approved), proceed to apply the decisions.\n - If the task exited with a non-zero status (abort), don't modify any issues. You MUST STOP and ask the user for further instructions.\n\n---\n\n### Step 4: Apply Decisions to GitHub\n\nOnce the dashboard task exits successfully, **Execute Approved Decisions**: Run the apply script to update the approved labels, assignees, and comments on GitHub:\n\n`python3 .agents/skills/a2ui-issue-triage/scripts/apply_triage.py --decisions-file \"/brain//scratch/triage_decisions.json\"`\n\n---\n\n## Bundled Resources\n\n- **[triage_criteria.md](references/triage_criteria.md)**: Authoritative guide for classifying issues, assigning priorities, and drafting response messages.\n- **`scripts/fetch_issues.py`**: Script to query open, untriaged issues via the GitHub CLI.\n- **`scripts/suggest_triage.py`**: Helper script to generate initial triage suggestions.\n- **`scripts/launch_dashboard.py`**: Local HTTP server that opens the interactive web dashboard in the user's browser.\n- **`assets/triage_dashboard.html`**: HTML/CSS/JS template for the triage review interface.\n- **`scripts/apply_triage.py`**: Script to apply finalized triage decisions to GitHub.\n",".agents/skills/a2ui-generate-pydantic-models/SKILL.md":"---\nname: a2ui-generate-pydantic-models\ndescription: Automated generator for strongly typed Pydantic v2 data models and basic catalogs across any A2UI protocol version (v0.8, v0.9, v0.9.1, v1.0, etc.).\n---\n\n# A2UI Pydantic Model Generation Skill\n\nThis skill provides an automated code generation tool that produces strongly typed Pydantic v2 data models and basic catalog definitions for `python/a2ui_core` directly from the schemas and catalogs in `specification//`.\n\n---\n\n## Agent Execution Steps\n\nWhen given a prompt like _\"Generate Pydantic model classes for A2UI spec v1.0\"_:\n\n1. **Extract the target version parameter from the prompt** (e.g. `v1.0` -> `v1.0`).\n\n2. **Execute the generator script exactly once for that target version**:\n\n ```bash\n uv run python .agents/skills/a2ui-generate-pydantic-models/scripts/codegen_pydantic.py --version \n ```\n\n _(Replace `` with the single requested version, e.g. `--version v1.0`)_.\n\n3. **Format generated Python code**:\n\n ```bash\n cd python/a2ui_core\n uv run pyink .\n ```\n\n4. **Verify the generated files** by running pytest:\n\n ```bash\n cd python/a2ui_core\n uv run pytest tests/test_codegen_pydantic.py\n ```\n\n5. **Stop and report completion to the user.**\n\n---\n\n## Generated Output Files per Version\n\nWhen executed for a target version `` (e.g. `v1.0` -> `v1_0`), the script generates:\n\n1. **`python/a2ui_core/src/a2ui/core/schema//`**:\n - `constants.py`\n - `common_types.py`: strongly typed shared models and the `COMMON_TYPES_DEFS` manifest, which maps each spec `$defs` name to its symbol in spec order. No spec schema is copied verbatim; the published common types schema is rebuilt from these symbols.\n - Type aliases such as `ComponentId`, `Child`, `ChildList` and the `Dynamic*` unions are registered as `Annotated[..., Field(description=...)]` with the spec descriptions, so the runtime JSON schema generator needs no per-def special cases. Dynamic unions list their members in spec order.\n - When a `Dynamic*` def constrains its function-call branch with a `returnType` const, the branch is `Annotated[FunctionCall, ReturnType(\"\")]`, which validates the return type and emits the spec's `allOf` in both modes. Any other branch shape fails generation.\n - Every model extends `SpecBaseModel` (hand-written in `schema/common_types.py`) and has no generated methods. Keywords that fields cannot produce are declared in the model config as `json_schema_extra=SchemaKeywords(...)`: it drops `additionalProperties` where the spec leaves it out and adds `returnType`, `unevaluatedProperties`, `title`, `allowedParents` and `oneOf` required-alternatives (see `_SPEC_KEYWORDS`). The keywords apply only to the declaring model, not to subclasses. `SpecBaseModel` validates a declared `oneOf` whose branches only list required fields (for example `FunctionResponse`'s `value`/`error`), requiring exactly one branch.\n - Only composition that references the catalog's function union is limited to `spec_schema()` (`SchemaKeywords(..., spec_only=True)`), which the published common types schema uses: v0.9's `FunctionCall` `oneOf`, v1.0's `FunctionCall` `allOf` over `FunctionCommon` and `anyFunction` (`replace=True`, since the spec def is pure composition), and v0.9's precise `args` shape (a schema-only `JsonSchemaAs` annotation requested through the `x-python-type` property override). Catalogs keep the flat model shape there. References inside declared keywords are the markers `def_ref(\"\")` and `catalog_functions()` from the internal `a2ui.core.schema._json_schema` module, which the schema builder resolves to `$ref`s. `FunctionCall` itself is a flat model that validates any call without the catalog.\n - Nested object properties with their own properties become helper models named `` (for example `ComponentCommonMetadata`, `IndexSystemFunctionArgs`, `FunctionResponseError`), which schemas inline. Wrapper unions such as `Action` are `TypeAliasType`s, so fields reference them by def name. Each branch gets a `Wrapper` model, and a branch property that is an object becomes `` (`ActionEvent`, `ActionEventWrapper`, `ActionFunctionCallWrapper`). A generated name that collides with a def, a base symbol or another helper fails generation.\n - A def that the spec leaves open (no `additionalProperties` and no `unevaluatedProperties: false`) allows extra keys. `ComponentCommon` is the exception (`_SUBCLASSED_DEFS`): generated catalog components subclass it and must stay closed.\n - Optional fields are typed `X | None` so they can be absent. `SpecBaseModel` rejects an explicit null for such a field unless `X` accepts null itself (`Any`), under both the spec name and the Python field name; it does not change the JSON schema. Catalog components inherit this rule through `ComponentCommon`. v0.9's `FunctionCall.args` also rejects null values.\n - Primitive defs such as `CallId` are `TypeAliasType`s, so local references keep their `$ref`. References from other documents to a primitive def map to its Python type through `_CROSS_DOCUMENT_REF_TYPES` in `engine.py`.\n - `patternProperties` objects (`Extensions`) are `TypeAliasType`s over a key-checking validator, and their pattern is published in the spec schema and in catalogs. Python's `re` cannot compile `\\p{...}`, so the SDK validates JSON schemas with `a2ui.core.validation.SchemaValidator` (powered by `regex`). The `DynamicValue` literal-object branch carries the spec's `propertyNames` and `not` clauses through a `SchemaKeywords` annotation in both modes.\n - Common types keep `component` properties (`Surface`) and emit required consts without defaults (`skip_component_property` and `required_const_default` on the engine). Spec defaults are emitted as JSON schema `default` values (`schema_defaults`), not as description notes.\n - Common types are generated in strict mode: a schema shape the models would not enforce (an unknown or non-local `$ref`, siblings next to `$ref`/`const`/composition, an unsupported keyword next to `properties`, a required property that is not declared, an empty union) raises instead of loosening validation. Output is deterministic and does not depend on string hashing.\n - `agent_to_renderer.py` / `server_to_client.py`: strongly typed outbound message models and the `AGENT_TO_RENDERER_DEFS` manifest, which maps each spec `$defs` (or v0.8 `properties`) name to its symbol in spec order so `get_agent_to_renderer_schema_map` / `get_agent_to_renderer_schema_json` can rebuild `server_to_client.json` / `agent_to_renderer.json` from the models. Nested payload objects and array item objects become helper models marked with `INLINE_DEF_MARKER` (for example `CreateSurfaceMetadata`, `SurfaceUpdateComponentsItem`), and non-message `$defs` (`Component`, `ComponentsList`) are emitted as `TypeAliasType`s with `SchemaKeywords`.\n - `renderer_to_agent.py` / `client_to_server.py`\n - `renderer_capabilities.py` / `client_capabilities.py`\n - `agent_capabilities.py` / `server_capabilities.py` (when present in spec)\n - `catalog_definition.py` (when present in spec)\n - `__init__.py`\n\n2. **`python/a2ui_core/src/a2ui/core/basic_catalog//`**:\n - `components.py` (strongly typed components & `ModelComponentApi` registrations)\n - `function_apis.py` (strongly typed function schemas & `FunctionApi` classes)\n - `styles.py` (theme schema, generated when theme is defined in catalog)\n - `__init__.py`\n - The models and the generated `BasicCatalog` carry everything `Catalog.to_json()` needs to rebuild the published catalog document from them, with no catalog JSON copied into Python or read at runtime:\n - `BasicCatalog` passes the document's top-level fields to `Catalog`: `$schema`, `$id`, `title`, `description`, `protocolVersion` (None when the document declares none), `catalogId` when it declares none, `instructions`, where it writes its theme (`theme_location`), its unions (`union_defs`, which must list the catalog's entries) and the document its common types references point into (`common_types_uri`). The theme is passed as `theme_model`.\n - Without common types (v0.8), nested objects become models that keep the document's shapes: two nested objects of different shapes never share a model (the later one is prefixed with its component or parent model, for example `SliderValueItem`), and their descriptions stay on the fields, with line breaks, rather than becoming docstrings. `Catalog.to_json()` writes them inline, as the v0.8 document does.\n - For versions with a common types schema (v0.9+), the models carry everything `Catalog.validation_schema` and `Catalog.to_json()` need to rebuild the specification's `catalog.json` shape from them:\n - A component's `allOf` references to common types defs (for example `Checkable`) become base classes, and catalog defs (`CatalogComponentCommon`) become base models. A component with more than one base sets `extra=\"forbid\"`, because Pydantic would otherwise inherit an open base's config. A component description becomes the class docstring and fails generation if it cannot be one.\n - A function's description becomes the `FunctionApi.description` attribute. Keywords on the `args` object that fields cannot produce (`unevaluatedProperties`, `additionalProperties`, required-alternative `anyOf`) are declared with `SchemaKeywords` as the model's `json_schema_extra`, and an unknown keyword fails generation.\n - Field constraints (`minItems`, `minimum`, ...) are emitted as `Field` arguments, so they are validated and published; `format` and `default` are published through `json_schema_extra`. An `allOf` member that only adds keywords becomes a `SpecAllOf` annotation.\n - The conformance cases `test_v08_basic_catalog_to_json`, `test_v09_basic_catalog_to_json` and `test_v10_basic_catalog_to_json`, and `python/a2ui_core/tests/test_basic_catalog_documents.py`, compare `BasicCatalog().to_json()` with the published files, so any drift fails the tests.\n\n3. **`python/a2ui_core/src/a2ui/core/schema/__init__.py`**:\n - Registers the version in `A2uiProtocolVersion` enum and updates envelope unions.\n",".agents/skills/a2ui-add-eval-datapoint/SKILL.md":"---\nname: a2ui-add-eval-datapoint\ndescription: Step-by-step workflow for adding and verifying new evaluation data points in the A2UI evaluation suite.\n---\n\n# Adding and verifying A2UI evaluation data points\n\nUse this skill when adding new data points or datasets to the A2UI evaluation framework in `eval/`.\n\n## References\n\nFor full architecture and setup details, consult:\n\n- `eval/CONTRIBUTING_USE_CASES.md`: The authoritative contributor guide for evaluation use cases, containing field definitions, context rules, and unencrypted multi-turn examples.\n- `eval/README.md`: Evaluation quickstart, Transcrypt setup, and CLI flags.\n- `eval/DESIGN.md`: Architecture, multi-stage scorers, and encryption-at-rest design.\n- `eval/datasets/dataset_schema.json`: Formal JSON Schema defining required fields and structural rules for evaluation data points.\n\n---\n\n## Step-by-step workflow\n\n### 1. Unlock Transcrypt\n\nDatasets in `eval/datasets/` are encrypted at rest. Unlock Transcrypt locally before authoring (ask an A2UI team member for the password):\n\n```bash\ncd eval\nbin/transcrypt -y -c aes-256-cbc -p \n```\n\n### 2. Author the data point\n\nCreate or update a dataset file in `eval/datasets/.yaml` (e.g. `eval/datasets/my_dataset.yaml`).\n\nEvery data point **must conform** to the JSON Schema in `eval/datasets/dataset_schema.json` and follow the authoring guidelines in `eval/CONTRIBUTING_USE_CASES.md`.\n\nFor a complete unencrypted reference example of a multi-turn conversation with system instructions, tool calls (including unrelated background tool calls), tool responses, and a judging target rubric, inspect `eval/examples/example_eval_case.json`.\n\n**Key authoring requirements from `eval/CONTRIBUTING_USE_CASES.md`:**\n\n- Include the full multi-turn conversation history (`messages`), including assistant function calls (`tool_calls`) and tool responses (`role: tool`). Do not use single-turn prompts.\n- Write the `target` as a qualitative judging rubric for the LLM-as-a-judge (what UI components must appear, data binding rules, and what errors to penalize). Do not include a hardcoded JSON string, as that ties the evaluation to a particular inference format.\n\n### 3. Validate schema compliance\n\nVerify that all data points satisfy `eval/datasets/dataset_schema.json`:\n\n```bash\ncd eval\nuv run python -m pytest tests/test_dataset.py\n```\n\n### 4. Run an evaluation on the new data point\n\nAlways execute an evaluation run on the newly added dataset to verify model inference and scoring:\n\n```bash\ncd eval\n# Quick validation on gemini-3.1-flash-lite\nuv run main.py --dataset my_dataset --sanity\n\n# Full evaluation check\nuv run main.py --dataset my_dataset\n```\n\nView the interactive traces and judging rationales:\n\n```bash\nuv run inspect view start\n```\n\n### 5. Verify encryption and commit\n\nWhen staging changes, Git applies the Transcrypt clean filter. Confirm that the staged file is encrypted ciphertext before committing:\n\n```bash\n# Stage the new dataset file\ngit add eval/datasets/my_dataset.yaml\n\n# Verify staged content is encrypted ciphertext (not plaintext)\ngit diff --cached eval/datasets/my_dataset.yaml\n\n# Commit the encrypted data point\ngit commit -m \"feat(eval): add my_dataset evaluation data points\"\n```\n",".agents/skills/a2ui-release-python/SKILL.md":"---\nname: a2ui-release-python\ndescription: Releases the Python SDKs (a2ui-core, a2ui-agent-sdk, a2ui-a2a, a2ui-adk) to PyPI by running preflight checks, dispatching the release workflow as a dry run, confirming with the maintainer, publishing, and following the changelog pull request through to merge. Use when asked to cut, publish, or release a Python SDK version.\n---\n\n# Releasing the A2UI Python SDKs\n\nThis skill turns a one-line request such as _\"release a2ui-core patch\"_ or\n_\"release the Python SDKs\"_ into the full release sequence.\n\nPublishing is done by the\n[Release Python SDKs](../../../.github/workflows/release-pypi.yml) workflow. This\nskill does not reimplement any of it. Its job is the part the workflow cannot do\nfor itself: choosing the bump, catching the problems that a workflow run would\ndiscover too late, and following through afterwards.\n\nBackground for anything not covered here:\n[docs/contributing/release.md](../../../docs/contributing/release.md).\n\n> [!CAUTION]\n> **Publishing to PyPI is irreversible.** A version can be yanked but never\n> reused or deleted. Step 5 is a mandatory stop. Never dispatch a run with\n> `dry_run: false` without an explicit go-ahead from the maintainer in the\n> current conversation.\n\n### What runs where\n\n**The workflow performs the release. Nothing here does.** Building, tagging,\npushing tags, staging in the Artifact Registry and triggering the Exit Gate all\nhappen inside `release-pypi.yml`, and only there. It could not be otherwise: the\nExit Gate authenticates by matching the OIDC claim\n`…/release-pypi.yml@refs/heads/main`, so a local upload has no credentials to\nuse.\n\n| Run locally | Run by the workflow |\n| :--------------------------------------------- | :------------------------------------------------ |\n| `release_version.py notes` | `release_version.py plan` (authoritative) |\n| `release_version.py plan` (preview only) | `release_version.py check` |\n| `release_version.py check` (preview only) | `release_version.py cut-changelog` |\n| `gh workflow run`, `gh run view`, `gh pr list` | `release_artifacts.py`, `confirm_pypi.py` |\n| | `uv build`, `twine upload`, `git tag`, `git push` |\n\nThe local calls are limited to the read-only subcommands `notes`, `next`,\n`current`, `tag`, `plan` and `check`. They exist to answer two questions before\nspending a CI run: is there anything to release, and will preflight reject it.\n\n> [!IMPORTANT]\n> A local `plan` is a **prediction**, not the release. It is computed from the\n> tags in the local checkout, so it is only as current as the last fetch — which\n> is why Step 2 fetches first. The plan the workflow computes is the one that\n> counts, and Step 4 reads it back out of the run before anyone approves it.\n\nNever run `cut-changelog --write`, `git tag`, `git push`, `uv build` or `twine`\nby hand to perform a release. If the workflow cannot do it, fix the workflow.\n\n> [!IMPORTANT]\n> One exception, and it is deliberate: **the changelog pull request has to be\n> opened by a person, not by the workflow.** GitHub does not start workflow runs\n> for events caused by `GITHUB_TOKEN`, so a pull request the workflow opened\n> would never get the required checks and could never be merged. The workflow\n> pushes the branch; Step 7 opens the pull request.\n\n## Step 1: Check environment prerequisites\n\nCheck that your local environment meets these prerequisites before proceeding.\nThe preflight check in Step 3 (`release_version.py check`) also validates these\nautomatically and stops with an `Action needed:` message for each one that\nfails. They are skipped in GitHub Actions, where they do not apply.\n\n1. **An a2ui checkout.** Run from your clone of `a2ui-project/a2ui`. The script\n finds the repository root itself, so a subdirectory works (it warns), but\n the commands below use paths relative to the root.\n2. **Python 3.11+.** The script reads `pyproject.toml` with the standard\n library `tomllib`. If your system `python3` is older, run it through the\n project toolchain instead: `uv run python .github/scripts/release_version.py\n...`.\n3. **GitHub CLI (`gh`)**, installed, authenticated with `github.com`, and with\n write access to `a2ui-project/a2ui`. It dispatches and watches the workflow\n and opens the changelog pull request.\n4. **Git identity.** `git config user.name` and `git config user.email` must be\n set, so the changelog commit and pull request pass CLA verification.\n5. **A remote that points at `a2ui-project/a2ui`.** It may be called `origin`\n in a direct clone or `upstream` beside a fork; the script finds it by URL.\n The commands below call it `${REMOTE}`:\n\n ```bash\n REMOTE=$(git remote -v | awk '/a2ui-project\\/a2ui(\\.git)?\\/? \\(fetch\\)/ {print $1; exit}')\n ```\n\n---\n\n## Step 2: Work out what is being released\n\nTwo things are needed: `PACKAGE` and `BUMP` (`patch`, `minor`, or `major`).\n`PACKAGE` names the packages to release, either as a comma-separated list of\npackage names or as `all`:\n\n- One package: `a2ui-agent-sdk`\n- Several packages: `a2ui-a2a,a2ui-adk`\n- Every package: `all` (`a2ui-core`, `a2ui-agent-sdk`, `a2ui-a2a`, `a2ui-adk`)\n\nThe workflow publishes the listed packages in dependency order (`a2ui-core`,\n`a2ui-agent-sdk`, `a2ui-a2a`, `a2ui-adk`), whatever order they are listed in.\nDerive `PACKAGE` and `BUMP` from the changelogs. Never infer them from the\nphrasing of the request.\n\nFetch first. Versions are derived from tags, so every number below is wrong if\nthe checkout is behind:\n\n```bash\ngit fetch \"${REMOTE}\" main --tags\n```\n\n```bash\nfor package in a2ui-core a2ui-agent-sdk a2ui-a2a a2ui-adk; do\n echo \"== ${package}\"\n python3 .github/scripts/release_version.py notes --package \"${package}\"\ndone\n```\n\n**Choose the packages.** Release only those with a non-empty `## Unreleased`.\nEmpty output means that package has nothing to release, whatever was asked for.\nA plural request such as _\"release the Python SDKs\"_ does not mean `all`. List\nexactly the packages with pending entries, for example\n`a2ui-agent-sdk,a2ui-a2a`. If only one has pending entries, that one is the\nrelease. If none does, stop and say so.\n\nCheck the exit status, not just the output. The two failure shapes are\ndifferent answers:\n\n| Result | Meaning | Do |\n| :------------------------- | :---------------------------------------------------------------- | :----------------------------------- |\n| exit 0, output | Entries pending | Release this package |\n| exit 0, no output | `## Unreleased` is empty | Skip this package |\n| exit 1, `error:` on stderr | Changelog is malformed, usually a missing `## Unreleased` heading | Stop. Report it and do not dispatch. |\n\n> [!NOTE]\n> Dispatching a package whose `## Unreleased` is empty is not dangerous, just wasteful. The\n> plan builds, then preflight rejects the empty package and the run fails\n> several minutes in. The check above costs a second.\n\n**Choose the bump.** Read the entries. Fixes only means `patch` and new\nfeatures mean `minor`. A breaking change means `minor` while the package is\nbelow 1.0, and `major` from 1.0 on. Preview the result with `plan`,\nwhich returns exactly what the workflow will compute — version, tag and release\nnotes for every selected package:\n\n```bash\npython3 .github/scripts/release_version.py plan --package \"${PACKAGE}\" --bump \"${BUMP}\"\n```\n\n> [!IMPORTANT]\n> **One run applies one bump level to every listed package.** The workflow\n> takes a single `bump` input, so `build_plan` raises every version by the same\n> amount. When the packages warrant different levels — say fixes in\n> `a2ui-core` and a feature in `a2ui-agent-sdk` — there is no single right\n> answer. Put the choice to the maintainer:\n>\n> - **Take the higher level for every listed package.** One release, one\n> changelog pull request. The cost is an over-bumped version on the quieter\n> packages.\n> - **Run one release per bump level.** Correct versioning, but the changelog\n> pull request from each run must be **merged before starting the next**, or\n> the Step 3 guard will block it. Release in dependency order: `a2ui-core`,\n> `a2ui-agent-sdk`, `a2ui-a2a`, `a2ui-adk`.\n\n> [!IMPORTANT]\n> **A minor or major `a2ui-core` bump may need a pin change first.**\n> `a2ui-agent-sdk` declares a range such as `a2ui-core>=0.3.0,<0.4.0` in\n> [a2ui_agent/pyproject.toml](../../../python/a2ui_agent/pyproject.toml). If\n> the proposed `a2ui-core` version falls outside it, widen the pin in its own\n> pull request and **merge it to `main` before dispatching**. The workflow\n> releases `main` as it is and cannot change package files during the run.\n> Step 3 rejects the release until this is done.\n>\n> The same applies down the chain: `a2ui-a2a` and `a2ui-adk` pin\n> `a2ui-agent-sdk` in their `pyproject.toml`, and `a2ui-adk` pins `a2ui-a2a`\n> in its `a2a` extra. A new version of a package must fall inside every pin on\n> it.\n\n> [!IMPORTANT]\n> **A dependent needs its dependencies on PyPI.** Releasing `a2ui-a2a` or\n> `a2ui-adk` on its own requires the released `a2ui-agent-sdk` (and, for\n> `a2ui-adk`, `a2ui-a2a`) to satisfy its pins already. If it does not, release\n> the dependency first, or list it in the same run. Step 3 reports\n> this as \"has not been released yet\" or \"requires ..., but the latest release\n> ... is ...\".\n>\n> **First release of a brand-new package.** A package with no tag yet starts\n> from `0.0.0`, so use a `minor` bump to release `0.1.0`. Before its first\n> release, the package name must be added to the OSS Exit Gate allowlist for\n> `a2ui/pypi` and registered as a **Pending Publisher** on\n> `https://pypi.org/manage/account/publishing/` under the **Google** tab with\n> email `a2ui-py@oss-exit-gate-prod.iam.gserviceaccount.com` and an empty\n> subject (see `go/a2ui-release#pypi`). PyPI indexes Google Cloud Pending\n> Publishers uniquely by `(email, sub)`, so **only one Pending Publisher can be\n> registered at a time**. Do not release two brand-new packages in the same\n> manifest: register and publish them one at a time so the first upload\n> promotes its Pending Publisher to a project-scoped Trusted Publisher before\n> registering the second.\n\nPut the proposal to the maintainer with `ask_question`, showing the pending\nentries and the resulting versions, and let them correct it.\n\n---\n\n## Step 3: Preflight locally\n\nThese checks cost seconds and catch the failures that are expensive to hit\nmid-run. Run all of them before dispatching anything.\n\n**1. The environment and the checkout.** `check` runs these for you (see\nStep 1: Check environment prerequisites); this is what it looks for and why:\n\n- **No outstanding changelog branch** from a previous release on `${REMOTE}`.\n Until the last release's changelog lands, its entries are still under\n `## Unreleased`, and this release would repeat them. It checks the branch,\n not the pull request, because the release stops at the branch and there may\n be no pull request yet. The repository deletes branches on merge, so no\n branch means the last changelog landed. If one is found, get that change\n merged (open the pull request if nobody has), then start over from Step 2,\n because the pending entries will have changed.\n- **The released packages match `${REMOTE}/main`.** The workflow builds from\n `main`, so `python/a2ui_core`, `python/a2ui_agent`, `python/a2ui_a2a` and\n `python/a2ui_adk` must be identical to it.\n Uncommitted edits, or a local commit that is not merged yet (a widened pin,\n say), would make the local preview describe a release that is not the one\n that will go out. Other paths in the checkout do not matter.\n\nIf it reports any of these, or any of the Environment Prerequisites, stop and\nsay what was found.\n\n**2. The repository's own preflight passes.** The package checks (changelog,\ntag, and pin) are the ones the workflow runs, so a failure in them here is a\nfailure there:\n\n```bash\n# Check using bump level (comma-separated package names, or 'all'):\npython3 .github/scripts/release_version.py check --package \"${PACKAGE}\" --bump \"${BUMP}\"\n\n# Or check a specific version directly (single package only):\npython3 .github/scripts/release_version.py check --package \"${PACKAGE}\" --version \"${VERSION}\"\n```\n\nIt rejects an empty `## Unreleased`, a version that already has a tag, a version\noutside the range that another package pins it to, and a dependency on another\npackage of this repository that no released version (or no version in the same\nrun) satisfies. With several packages and `--bump`, it evaluates every listed\npackage and their cross-dependency pins in a single step.\n\nIf preflight reports a pin problem, stop: see the pin notes in Step 2.\n\n---\n\n## Step 4: Dry run\n\nA dry run builds and stages the artifacts in the Exit Gate Artifact Registry,\nremoves them again, and pushes nothing.\n\n```bash\ngh workflow run release-pypi.yml --repo a2ui-project/a2ui --ref main \\\n -f package=\"${PACKAGE}\" -f bump=\"${BUMP}\" -f dry_run=true\n```\n\nWait a few seconds, then find the run and watch it:\n\n```bash\ngh run list --repo a2ui-project/a2ui --workflow=release-pypi.yml --limit 1 \\\n --json databaseId,status,url\ngh run watch \"${RUN_ID}\" --repo a2ui-project/a2ui --exit-status\n```\n\n> [!TIP]\n> Use the full `databaseId`. A truncated run ID returns 404.\n\nIf it fails, read the failing step's log and consult Troubleshooting below\nbefore retrying.\n\nWhen it passes, read back the plan the run actually computed. The dry run does\nnot upload the plan artifact, and step summaries are not available over the API,\nbut the plan step prints the JSON into the log:\n\n```bash\ngh run view \"${RUN_ID}\" --repo a2ui-project/a2ui --log \\\n | grep -A 20 'Build the release plan'\n```\n\nCompare it against the local `plan` output from Step 2. They are computed the\nsame way and should agree. If they differ, a tag landed in between — stop and\nwork out why before going any further.\n\n---\n\n## Step 5: Confirm with the maintainer\n\n**Stop here.** Show the maintainer:\n\n- the exact versions and tags from the dry run's plan,\n- the changelog entries that will become the release notes,\n- that the dry run passed.\n\nQuote the version numbers in full, for example `a2ui-agent-sdk 0.7.0`. Do not\ndescribe the release only as \"a minor bump\" — the bump level is the input, the\nversion is the irreversible consequence, and it is the version the maintainer\nneeds to approve.\n\nThen ask for explicit confirmation to publish. Proceed only on a clear yes.\n\n---\n\n## Step 6: Publish\n\n```bash\nAUTHOR_NAME=$(git config user.name)\nAUTHOR_EMAIL=$(git config user.email)\ngh workflow run release-pypi.yml --repo a2ui-project/a2ui --ref main \\\n -f package=\"${PACKAGE}\" -f bump=\"${BUMP}\" -f dry_run=false \\\n -f author_name=\"${AUTHOR_NAME}\" -f author_email=\"${AUTHOR_EMAIL}\"\n```\n\nWatch it as in Step 4. The run pushes the tags, stages the artifacts, uploads\nthe manifest that triggers the Exit Gate, and creates the GitHub releases.\n\nFour jobs follow:\n\n| Job | What it does | If it fails |\n| :---------- | :----------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- |\n| `build` | Runs tests and builds distributions | Test failure or malformed distribution. See Troubleshooting. |\n| `release` | Stages, tags, and triggers publishing | Real failure. See Troubleshooting. |\n| `confirm` | Polls PyPI, then links the GitHub releases | A timeout is not a failure. The hourly [Confirm PyPI publication](../../../.github/workflows/release-verify-pypi.yml) workflow finishes the job. |\n| `changelog` | Pushes the changelog branch | Publishing already succeeded. Cut the changelog by hand and open the PR yourself. |\n\n> [!IMPORTANT]\n> **The run stays active for several minutes after `release` goes green, and\n> that is normal.** Triggering the Exit Gate is not publishing. The Exit Gate\n> works asynchronously and reports only by email, so the `confirm` job sits and\n> polls PyPI every 30 seconds for up to 20 minutes waiting for the version to\n> appear.\n>\n> `gh run watch` blocks until all three jobs finish, so it is the wait. Let it\n> run. Do not poll PyPI in a loop alongside it, and do not report the release as\n> finished — or as failed — while `confirm` is still in progress.\n\n---\n\n## Step 7: Follow through\n\nA release is not done when the workflow goes green.\n\n1. **Confirm the version is live.** The waiting has already happened on the\n runner, so read the `confirm` job's outcome rather than starting a fresh\n wait:\n\n - **`confirm` succeeded** — the version is on PyPI and the GitHub releases\n have been updated with links. Verify once and move on:\n\n ```bash\n curl -s -o /dev/null -w '%{http_code}\\n' \"https://pypi.org/pypi/${PYPI_NAME}/${VERSION}/json\"\n ```\n\n `200` confirms it. A `404` here, after `confirm` reported success, is a CDN\n lag of a minute or two — wait briefly and check again.\n\n - **`confirm` timed out** — publishing took longer than 20 minutes. **This is\n not a failed release.** The artifacts are staged and the Exit Gate still\n has them. Do not re-run the release, and do not try to publish the version\n again: that would burn a version number. Tell the maintainer it is\n outstanding, and leave it to the hourly\n [Confirm PyPI publication](../../../.github/workflows/release-verify-pypi.yml)\n workflow, which finds the release by its pending marker and links it once\n PyPI catches up. The Exit Gate also emails\n `a2ui-core-working-group@google.com` with the outcome either way.\n\n - **`confirm` failed for another reason** — read the log. The publish itself\n may still have succeeded, so check PyPI before concluding anything.\n\n2. **Open the changelog pull request and get it merged.** The release pushed the\n branch but deliberately did not open the pull request — see \"What runs\n where\". Open it yourself:\n\n ```bash\n BRANCH=$(git ls-remote --heads \"${REMOTE}\" 'release/changelog-*' \\\n | sed 's#.*refs/heads/##')\n gh pr create --repo a2ui-project/a2ui --base main --head \"$BRANCH\" \\\n --title \"chore(release): changelog for ${RELEASED}\" \\\n --body \"Moves the \\`## Unreleased\\` entries under the released versions.\"\n ```\n\n Check the diff touches only `CHANGELOG.md` files, then ask the maintainer to\n review it. Do not leave it open: Step 3 blocks the next release until the\n branch is gone.\n\n3. **Report** the published versions, the GitHub release links, and the\n changelog pull request link.\n\n---\n\n## Troubleshooting\n\n**`could not find any workflows named release-pypi.yml`** — the workflow is only\ndispatchable once it is on `main`. Check it has merged.\n\n**HTTP 403 from Artifact Registry** — the Exit Gate allowlists\n`a2ui-project/a2ui` only. This is the expected result on a fork, and not a bug.\nOn the real repository it means the builder identity no longer matches; see\n`go/oss-exit-gate-builders`.\n\n**`Permission denied` or a failed OIDC exchange** — the Exit Gate matches the\nworkflow path and branch exactly:\n\n```\ngithub_workflow:a2ui-project/a2ui/.github/workflows/release-pypi.yml@refs/heads/main\n```\n\nRenaming or moving the workflow file breaks releases until the internal config\nis updated. It also cannot be triggered from a branch or a tag, only `main`.\n\n**`... is already on PyPI`** — the version was published previously. It cannot be\nrepublished. Work out why the tag series and PyPI disagree before retrying.\n\n**`One or more packages are not in the project's allowlist` or `400 Non-user identities cannot create new projects` in Exit Gate logs**: a brand-new package name must be added to the OSS Exit Gate allowlist and registered as a Pending Publisher on `https://pypi.org/manage/account/publishing/` before its first release. Because PyPI allows only one Pending Publisher at a time for `a2ui-py@oss-exit-gate-prod.iam.gserviceaccount.com`, publish brand-new packages one at a time. See [docs/contributing/release.md](../../../docs/contributing/release.md#releasing-a-new-package-for-the-first-time) and `go/a2ui-release#pypi`.\n\n**A dry run or failed staging left artifacts behind** — the cleanup step runs\neven on partial failure, but if it was itself skipped, remove the staged version\nby hand:\n\n```bash\ngcloud artifacts versions delete \"${VERSION}\" --package=\"${PYPI_NAME}\" \\\n --repository=a2ui--pypi --location=us --project=oss-exit-gate-prod --quiet\n```\n\n---\n\n## Rules\n\n- Never edit a version by hand. Versions come from git tags via `hatch-vcs`, and\n the workflow verifies the built artifacts against the version it planned.\n- Never push tags or run the release scripts locally to publish. The scripts\n under `.github/scripts/` are safe to run read-only for `notes`, `next`,\n `current`, `tag`, and `check`. Everything else belongs to the workflow.\n- Never dispatch `dry_run: false` without the Step 5 confirmation.\n- If the maintainer asks to skip the dry run, push back once: it is the only\n rehearsal before an irreversible publish. Defer if they insist.\n",".agents/skills/a2ui-test-quality-check/SKILL.md":"---\nname: a2ui-test-quality-check\ndescription: Auditing test suites for assertion utility, boundary cases coverage, and verification strength.\n---\n\n# A2UI Test Quality & Assertions Auditing Skill\n\nThis skill guides you through the process of auditing codebase test suites to verify that tests are providing robust, meaningful assertions and verifying critical invariants, rather than simply running paths for code coverage.\n\n---\n\n## **Instructions**\n\n1. **Locate Test Suites**:\n - Find all test directories and test files in each platform's implementation folder (e.g. `tests/`, `test/`, `*Tests.swift`).\n\n2. **Audit Assertion Quality**:\n - For each test case, inspect the assertions used:\n - Flag \"weak assertions\" that only verify non-null or truthy values without checking specific payload structure, field values, or types (e.g. `expect(result).not.toBeNull()` on a complex object).\n - Flag \"empty tests\" that execute code blocks but lack any assertions or mocks verifications (e.g. executing to check for lack of exceptions, unless it is explicitly marked as a no-throw smoke test).\n - Ensure that return models, state side effects, and events dispatched have corresponding value-matching assertions.\n\n3. **Audit Behavioral and Boundary Coverage**:\n - Review if tests exist for typical logical edge cases:\n - Null, empty, or overflow values.\n - Invalid JSON or parsing errors (e.g., throwing correct exceptions).\n - Exception propagation and error boundaries.\n - Timeout handling and cleanup side effects.\n - Look for cases where tests might pass when they should fail.\n - Cross-reference with the codebase's main files: if a file has complex parsing/validation code, ensure there are dedicated failing test cases asserting that errors are reported correctly.\n\n4. **Audit Mocking Realism**:\n - Ensure mocks and stubs verify their call parameters (e.g., verifying that a mock transport received the exact payload sent by the SDK, rather than just asserting it was called).\n\n5. **Format the Report**:\n - Build a Markdown report summarizing the findings:\n - Table of audited test suites and files.\n - **Weak Assertions**: List of test cases that rely on weak or missing assertions.\n - **Missing Edge Case Tests**: Critical logic boundaries and exception paths lacking tests.\n - **Mocking Mismatches**: Mock implementations that fail to verify call structures.\n - Return this Markdown report as your final response.\n",".agents/skills/a2ui-remediate-problem/SKILL.md":"---\nname: a2ui-remediate-problem\ndescription: Remediates a specific recommendation from an A2UI compliance report issue, or resolves any general GitHub issue, by inspecting context, implementing minimal targeted fixes, verifying tests, creating a branch, and opening a developer-signed Pull Request. Use when asked to fix or remediate an A2UI compliance audit finding, recommendation, or repository issue.\n---\n\n# A2UI Issue & Compliance Remediation Skill\n\nThis skill guides an AI coding agent or engineer on how to remediate a specific recommendation from an A2UI compliance report or resolve any general repository issue and submit a clean, developer-signed Pull Request.\n\n---\n\n## **Workflow**\n\nFollow these steps to remediate an issue:\n\n### Step 1: Identify & Read Issue Context\n\n1. **Determine the Target Issue**:\n - If the user provided an issue number or URL in their request, extract `ISSUE_NUMBER`.\n - If no issue was specified, ask the user (prefer using the `ask_question` tool):\n _\"Which GitHub issue would you like to remediate? (Please provide the issue number or URL, e.g. 2391)\"_\n\n2. **Retrieve Context & Determine Issue Type**:\n - Run the helper script to inspect the issue:\n ```bash\n python3 .agents/skills/a2ui-remediate-problem/scripts/extract_recommendation.py \"${ISSUE_NUMBER}\" [RECOMMENDATION_INDEX] --json\n ```\n - **Scenario A: Compliance Report with Multiple Recommendations**:\n - If a recommendation index was provided (e.g. `2`), the script extracts that item's details and priority.\n - If no recommendation index was specified, the script outputs all available recommendations in the issue. Ask the user (via `ask_question`) which recommendation item they would like to address.\n - Review the surrounding audit sections in the report (such as `## Codebase Blueprint Compliance Audit`, `## Code & Documentation Sync Audit`, or `## Test Quality & Assertions Audit`) for detailed findings.\n - **Scenario B: General Issue (Bug Report, Feature Request, or Non-Audit Issue)**:\n - If the issue is not a compliance report, the script returns the issue title and body as the problem statement to remediate.\n\n---\n\n### Step 2: Formulate & Apply Remediation\n\n1. Identify the files and codebases referenced by the issue or recommendation.\n2. Carefully inspect the current source code, documentation, or blueprint files.\n3. Implement the minimal necessary change to remediate the reported problem.\n - **CRITICAL RULE**: Do not make unrelated changes, refactorings, or formatting edits outside the scope of the target issue or recommendation.\n4. Format modified files and ensure code style compliance:\n ```bash\n ./scripts/fix_format.sh\n ```\n5. If modifying tests or scripts, execute local tests across the affected packages to ensure no regressions were introduced.\n\n---\n\n### Step 3: Choose Destination & Create Workspace / Branch\n\n1. Check with the user on where they would like the changes created and what branch name to use (prefer using the `ask_question` tool or equivalent interactive tool if available):\n - **Recommended branch name**: `remediation/issue-${ISSUE_NUMBER}-${RECOMMENDATION_INDEX}` (or `remediation/issue-${ISSUE_NUMBER}` for general issues).\n - Let the user choose whether to create a separate git worktree (using their preferred local worktree conventions), checkout a new branch in the current directory, or apply changes in place.\n2. Note the chosen branch name in `BRANCH_NAME`.\n3. Ensure the working tree is clean and up to date with `upstream/main`.\n\n---\n\n### Step 4: Commit Changes\n\n1. Stage all modified files relevant to the remediation:\n ```bash\n git add -u\n ```\n2. Create a conventional commit referencing the issue number:\n - For compliance recommendations:\n ```bash\n git commit -m \"fix(compliance): remediate issue #${ISSUE_NUMBER} recommendation ${RECOMMENDATION_INDEX}\"\n ```\n - For general issues:\n ```bash\n git commit -m \"fix(scope): remediate issue #${ISSUE_NUMBER} - ${CONCISE_SUMMARY}\"\n ```\n\n---\n\n### Step 5: Create Pull Request & Notify Issue (Optional / Upon Request)\n\n1. Check with the user whether they would like to submit a Pull Request (prefer using the `ask_question` tool or equivalent interactive tool if available):\n - **Recommended default**: Submit as a Draft PR (`--draft`) so CI checks run while allowing final review before requesting maintainer approvals.\n - Alternatively, submit directly as ready for review, or skip PR creation if the user wants to inspect changes locally first.\n2. If submitting a PR, generate a clear, descriptive PR title following Conventional Commits that concisely explains the specific fix being made (e.g. `fix(swift): create missing top-level README in swift/core`). **Do NOT include generic issue or recommendation numbers in the PR title.**\n3. Draft the PR description into a temporary file `pr_description.md` following [pr-description-template.md](references/pr-description-template.md).\n4. Push the branch to `origin` (or user's fork) and create the Pull Request against `main`:\n ```bash\n git push -u origin \"${BRANCH_NAME}\"\n PR_URL=$(gh pr create --draft \\\n --repo a2ui-project/a2ui \\\n --head \"${BRANCH_NAME}\" \\\n --base main \\\n --title \"${PR_TITLE}\" \\\n --body-file pr_description.md)\n ```\n _(Note: Omit `--draft` if the user prefers an immediate ready-for-review PR. If pushing from a fork, `gh pr create` automatically resolves the fork's head branch or accepts `--head :${BRANCH_NAME}`.)_\n5. Clean up the temporary file `pr_description.md`.\n6. Comment on the original issue to notify maintainers of the new PR:\n ```bash\n gh issue comment \"${ISSUE_NUMBER}\" \\\n --repo a2ui-project/a2ui \\\n --body \"🤖 Automated remediation triggered! Created PR (${PR_URL}) on branch \\`${BRANCH_NAME}\\` to address recommendation ${RECOMMENDATION_INDEX}.\"\n ```\n\n---\n\n## **References**\n\n- Refer to the [PR description template](references/pr-description-template.md) for PR body structure and guidelines.\n- Refer to the [`gh-reference`](../a2ui-audit/references/gh-reference.md) for GitHub CLI commands.\n",".agents/skills/natural-writing/SKILL.md":"---\nname: natural-writing\ndescription: Contains well-defined rules for creating natural, accurate, and readable writing. Use this skill whenever authoring longer text, including reports, PR descriptions, READMEs, system designs, analysis documents, or general documentation.\n---\n\n# Rules for natural writing\n\nThis document outlines strict rules to avoid common \"AI-isms\": stylistic and structural patterns that language models typically fall into. Follow these rules to produce content that is more understandable, and reads as natural, human-authored text.\n\nThe rules are numbered so that reviews can cite them, as in \"rule 3.2\".\n\n## 1. Vocabulary & phrasing controls\n\n### 1.1. The \"banned\" list\n\nAvoid words that are statistically overrepresented in AI text. Use simpler, more direct alternatives.\n\nAvoid verbs that are commonly overused, such as delve, underscore, highlight (as a verb), foster, cultivate, maximize, leverage, democratize, ensure, align with, resonate with, encompass, and bridge. Also avoid adverbs like seamlessly and extensively.\n\nFor nouns, avoid abstract uses of tapestry, landscape, realm, testament, interplay, synergy, cornerstone, hub, and ecosystem.\n\nFor adjectives, avoid puffery and vague descriptors like pivotal, crucial, vibrant, intricate, nuanced, unwavering, indelible, uncharted, rapidly evolving, transformative, breathtaking, nestled, dynamic, comprehensive, intuitive, holistic, robust, frictionless, scalable, and synergistic.\n\n### 1.2. Avoid \"copula\" substitutions\n\nDo not replace simple \"is\" or \"are\" verbs with flowery equivalents.\n\n- Instead of: \"The library _serves as_ a center for learning.\"\n- Write: \"The library _is_ a center for learning.\"\n- Instead of: \"The statue _stands as_ a monument to...\"\n- Write: \"The statue _is_ a monument to...\"\n\n### 1.3. Eliminate \"elegant variation\"\n\nDo not use synonyms just to avoid repeating a subject's name (e.g., \"the eponymous character,\" \"the titular protagonist,\" \"the celebrated author\"). It is acceptable to repeat the name or use pronouns naturally.\n\n### 1.4. Prefer literal words to idioms\n\nChoose the word that states the meaning directly over an idiom whose meaning depends on context. Idioms are harder to read for non-native speakers and for anyone skimming instructions.\n\n- Instead of: \"Leave the version _alone_.\"\n- Write: \"Leave the version _untouched_.\"\n\n### 1.5. Name things in full for a reader without your context\n\nUse the full name of a term when first mentioning it. Shorthand that was clear during development—such as an informal name for a part of the codebase may be meaningless to reviewers and future readers who lack that context.\n\n- Instead of: \"The suites are read through `_plain`.\"\n- Write: \"The conformance suites (the YAML test cases under `conformance/`) are read through `_plain`.\"\n\n## 2. Content & tone\n\n### 2.1. No \"puffery\" or forced significance\n\nDo not inflate the importance of a topic with vague praise. If a subject is important, the facts should demonstrate it without help.\n\nAvoid phrases like \"serves as a testament to,\" \"marking a pivotal moment,\" \"underscoring the importance of,\" \"leaving an indelible mark,\" or \"shaping the landscape.\"\n\n- Instead of: \"The founding of the institute marked a pivotal moment in the evolution of regional statistics, representing a significant shift toward independence.\"\n- Write: \"The institute was founded in 1989 to collect regional statistics.\"\n\n### 2.2. No superficial analysis\n\nAvoid attaching \"dangling\" present-participle phrases that offer vague commentary.\n\nDelete clauses starting with \"highlighting,\" \"emphasizing,\" \"reflecting,\" \"showcasing,\" or \"demonstrating\" if they just restate the obvious or add fluff.\n\n- Instead of: \"The building uses blue glass, _reflecting the region's natural beauty and symbolizing unity._\"\n- Write: \"The building uses blue glass.\"\n\n### 2.3. Avoid promotional language\n\nMaintain a neutral tone. Avoid \"advertisement\" words like boasts, features (as a verb), offers, premier, leading, state-of-the-art, committed to, and dedicated to.\n\n- Instead of: \"Nestled in the heart of the city, the hotel boasts a vibrant atmosphere.\"\n- Write: \"The hotel is located in the city center.\"\n\n### 2.4. No \"challenges and future outlook\" formula\n\nLanguage models often end articles with a generic \"Despite challenges... remains important\" conclusion. Do not end with a summary paragraph starting with \"Despite [X], [Subject] continues to...\" or speculating on the future. End with the last fact.\n\n- Bad: \"Despite facing economic hurdles, the company continues to thrive and remains a beacon of innovation.\"\n\n### 2.5. No \"title as proper noun\" leads\n\nDo not treat a descriptive article title (like a list or broad topic) as a proper noun in the first sentence.\n\n- Instead of: \"_The List of songs about Mexico_ is a curated compilation...\"\n- Write: \"This list contains songs about Mexico...\"\n\n### 2.6. No generic \"see also\" links\n\nDo not populate \"See Also\" sections with broad, generic terms. Links must be directly relevant and specific to the subject.\n\n- Bad: Linking _Financial technology_ in an article about a specific startup.\n- Good: Linking a competitor or specific related technology.\n\n### 2.7. Attribution precision\n\nAvoid vague \"weasel words\" like \"Experts argue,\" \"Observers have noted,\" or \"Several sources indicate\" unless you cite specific people immediately. Do not claim a subject interacts with a \"broader\" history or trend unless a source explicitly says so.\n\n## 3. Sentence structure\n\n### 3.1. No negative parallelism\n\nAvoid sentences that structure a contrast unnecessarily.\n\n- Instead of: \"It is _not only_ a painting, _but also_ a representation of...\"\n- Instead of: \"It is _not_ just about X; _it is_ about Y.\"\n- Write: \"It is a painting that represents...\"\n\n### 3.2. No \"rule of three\"\n\nAvoid listing exactly three adjectives or three noun phrases to sound \"comprehensive.\"\n\n- Bad: \"The event brings together _marketers, engineers, and designers_.\" (Unless those specific three groups are the _only_ ones).\n- Bad: \"It is _bold, innovative, and unique_.\"\n\n### 3.3. No false ranges\n\nDo not use \"from X to Y\" unless X and Y are endpoints of a logical scale (like time or size).\n\n- Instead of: \"The book covers everything _from_ biology _to_ space travel.\" (These are just two random topics, not a range).\n- Write: \"The book covers topics including biology and space travel.\"\n\n## 4. Structure & formatting\n\n### 4.1. Headers\n\nUse sentence case for headers (e.g., \"Early life,\" not \"Early Life\"). Do not use title case in headers.\n\n### 4.2. Formatting avoidance\n\nDo not use inline-header lists (such as `* **Header:** Description...`). Instead, use prose or simple lists.\n\nAvoid excessive bolding of keywords, \"key takeaways,\" or names in the body text, except for the first mention in the lead.\n\nUse numbered lists (`1.`, `2.`) instead of bullets, so readers can refer to an item by its number, as in \"see point 3\" (except in changelogs, which use `-` bullets; see [`update-changelog`](../update-changelog/SKILL.md)). Do not use emojis (🚀, 🧠) as list markers.\n\nAvoid creating tables for simple information that easily fits in a sentence.\n\nEnsure markup is context-appropriate; do not use Markdown (like `##`) in formats that do not support it (like Wikitext) unless it is explicitly converted.\n\n### 4.3. Punctuation\n\nUse straight quotes (`\"`, `'`) and straight apostrophes (`'`). Do not use curly or smart quotes (`“`, `’`).\n\nUse em dashes sparingly, as language models often overuse them for emphasis. Prefer commas or parentheses instead.\n\n## 5. Citations & integrity\n\n### 5.1. No hallucinations\n\nNever generate a citation unless you are looking at the source.\nDo not invent URLs or DOIs.\nDo not assume a book exists or contains a specific fact without verification.\n\n### 5.2. Link what you mention\n\nLink everything the reader may want to open: files, functions, test and conformance cases, packages, issues, pull requests, and external pages. How precise a link should be depends on how long the text lives.\n\n1. In short-lived text, such as review comments, PR descriptions, and issues, link to the exact lines. Pin the link to a commit SHA rather than a branch, so it keeps pointing at the lines you meant after the branch moves. For a Markdown file, add `?plain=1` so a line anchor such as `#L10-L20` works.\n2. In long-lived documents, such as READMEs, documentation, skills, and code comments, link to the file or its section, without line ranges. A line range in one long-lived document has to be updated every time the document it points to changes.\n3. Link only to what the reader can see at the link target. If your change is not pushed yet, link to the current version, or post the text after the push.\n4. Before posting, check that every link resolves.\n\n## 6. Communication (chat context)\n\nAvoid collaborative filler at the start of responses, such as \"Certainly!\", \"Here is the information,\" or \"I hope this helps.\" State the content directly.\n\nDo not apologize for being an AI or mention knowledge cutoffs unless it is relevant to a specific, time-sensitive fact.\n\nDo not preface responses with subject lines.\n\nKeep edit summaries concise and informal, avoiding verbose paragraphs.\n",".agents/skills/inspect-ai/SKILL.md":"---\nname: inspect-ai\ndescription: Useful when working with the Inspect AI evaluation framework (e.g., in the eval/ directory). Provides instructions on how to access Inspect AI documentation.\n---\n\n# Inspect AI Framework Guidelines\n\nWhen you are tasked with creating, modifying, or debugging evaluation scripts (especially within the `eval/` directory) that utilize the **Inspect AI** framework, you should consult the official documentation to ensure you are using the correct APIs, solvers, scorers, and best practices.\n\n### Documentation Source\n\nTo learn how to use Inspect AI, read the official LLM-optimized documentation guide by fetching the following URL using your `read_url_content` tool:\n\n`https://inspect.aisi.org.uk/llms.txt`\n\nAlways reference this document when you need clarification on how Inspect AI handles task execution, scoring objects, parallelism, or tool calling architectures.\n",".agents/skills/coding-principles/SKILL.md":"---\nname: coding-principles\ndescription: >-\n Enforces engineering, architecture, public API, and code quality standards distilled from human\n reviewer feedback across A2UI pull requests. Use when authoring new code, refactoring, addressing\n review feedback, or reviewing PR diffs. Don't use for release publishing or spec blueprint\n generation without code or PR changes.\n---\n\n# Skill: coding-principles\n\n**Purpose**: Core engineering, architecture, and code quality standards established by human reviewers across A2UI pull requests. Used by agents when authoring changes, refactoring code, addressing review feedback, or reviewing pull request diffs to maintain repository health across all languages.\n\n---\n\n## Specification and Blueprint Grounding\n\nBefore modifying or implementing code in any language, consult the authoritative specifications and blueprints:\n\n- **Protocol JSON Schemas**: [`specification/v0_9_1/json/`](../../../specification/v0_9_1/json/) and [`specification/v1_0/json/`](../../../specification/v1_0/json/) define wire-format envelopes, types, and validation constraints.\n- **Component Catalogs**: [`catalogs/basic/v1/catalog.json`](../../../catalogs/basic/v1/catalog.json) defines standard components, properties, and function signatures.\n- **Core Module Blueprint**: [`a2ui_core.blueprint.md`](../../../blueprints/modules/a2ui_core.blueprint.md) specifies state containers (`DataModel`, `SurfaceModel`), `MessageProcessor`, JSON pointer rules, auto-vivification, and error semantics.\n- **Agent SDK Blueprint**: [`a2ui_agent.blueprint.md`](../../../blueprints/modules/a2ui_agent.blueprint.md) specifies `A2uiGenerator`, `A2uiRequestProcessor`, inference format strategies, and prompt generation.\n- **Framework Adapter Blueprint**: [`a2ui_framework_adapter.blueprint.md`](../../../blueprints/modules/a2ui_framework_adapter.blueprint.md) specifies view mapping, reactive subscription lifecycles, and layout behavior.\n- **Typesafe Builder Blueprint**: [`typesafe_builder_api.blueprint.md`](../../../blueprints/features/typesafe_builder_api.blueprint.md) specifies fluent builder hierarchies.\n- **Reference Implementation**: [`typescript/core/web_core/`](../../../typescript/core/web_core/) serves as the canonical behavioral reference for edge-case resolution.\n\n---\n\n## Progressive Discoverability: Two-Level Subskill Routing\n\nBecause the A2UI repository spans multiple languages (`typescript/`, `python/`, `dart/`, `swift/`) and shared specifications (`specification/`, `catalogs/`), agents must use a two-level progressive discovery workflow:\n\n1. **Level 1 (Cross-Language Subskills)**: Activate language-agnostic principles that govern pull request scope, software design, public API boundaries, specification immutability, and changelogs across the entire monorepo.\n2. **Level 2 (Language-Specific Routing)**: Route by the programming languages modified in the diff to load only the subskills and language guides relevant to those languages.\n\n### Step 1: Inspect the PR Diff\n\nReview the modified files and categories of changes:\n\n```bash\n# In an active branch:\ngit diff main --stat\n```\n\nIdentify both:\n\n- **Cross-cutting functional areas** impacted (public exports, specifications, catalogs, changelogs, PR structure).\n- **Programming languages and directories** touched (`typescript/`, `python/`, `dart/`, `swift/`, `samples/`, `tools/`).\n\n---\n\n### Step 2: Activate Cross-Language Subskills (Language-Agnostic)\n\nEvaluate the cross-language subskills below against the diff and read any activated document in full:\n\n#### 1. PR Hygiene, Atomicity, Scope Control & Software Design\n\n- **Skill**: [`pr-hygiene`](../pr-hygiene/SKILL.md)\n- **Activate if**: Always applicable when authoring, preparing, or reviewing a pull request.\n\n#### 2. Public API Boundaries, Cross-Framework Design & Changelogs\n\n- **Document**: [`subskills/public-api-and-cross-framework-design.md`](subskills/public-api-and-cross-framework-design.md)\n- **Activate if**:\n - Any package entrypoint or facade (`index.ts`, `public-api.ts`, `package.json`, `__init__.py`, `lib/*.dart`, or public Swift API), or any `CHANGELOG.md` is modified.\n - Any new class, function, interface, type, model, or DI token is exported.\n - Renderer APIs, registration helpers, or adapters across `@a2ui/angular`, `@a2ui/lit`, `@a2ui/react`, `a2ui_flutter`, or `A2UISwiftUI` are modified.\n - Imports between sibling packages change.\n - Files under `specification/` or `catalogs/` (schemas, catalog fixtures, or examples) are modified or added.\n - Breaking changes or public API deprecations are introduced.\n - A new source file is added (verify it has a single responsibility rather than acting as a catch-all `types.*` or `utils.*` file).\n\n#### 3. Updating Changelogs (`CHANGELOG.md`)\n\n- **Skill**: [`update-changelog`](../update-changelog/SKILL.md)\n- **Activate if**: Any `CHANGELOG.md` is modified or a published package's public API or consumer-observable behavior changes.\n\n---\n\n### Step 3: Route by Language for Language-Dependent Principles\n\nInspect the file extensions and directories in `git diff main --stat` and follow the matching language route(s) below. Only load routers and guides for languages present in your diff:\n\n| Language / Ecosystem | Matching Paths & Extensions | Progressive Discovery Target |\n| :-------------------------------------------------------------- | :--------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **TypeScript & Web** (Lit, Angular, React, Web Core, CSS, HTML) | `*.ts`, `*.tsx`, `*.css`, `typescript/`, `samples/client/{lit,angular,react}/`, `tools/` | Read the TypeScript & Web router: [`subskills/typescript/INDEX.md`](subskills/typescript/INDEX.md) to activate specific TypeScript, reactive lifecycle, CSS theming, accessibility, DOM testing, and AST public API subskills. |\n| **Python** (Core, Agent SDK, Builders, Evaluators, Scripts) | `*.py`, `python/`, `eval/`, `samples/agent/`, `tools/`, `scripts/` | Read the Python router: [`subskills/python/INDEX.md`](subskills/python/INDEX.md) to activate Python package architecture, facade conventions, typing, and verification subskills. |\n| **Swift & SwiftUI** (Core, SwiftUI Adapter, iOS Sample) | `*.swift`, `swift/`, `Package.swift` | Read the Swift & SwiftUI router: [`subskills/swift/INDEX.md`](subskills/swift/INDEX.md) to activate Swift target architecture, coding standards, and `Testing` subskills. |\n| **Dart & Flutter** (Core, Agent SDK, Flutter Adapter) | `*.dart`, `dart/`, `samples/client/flutter/`, `pubspec.yaml` | Read the Dart & Flutter router: [`subskills/dart/INDEX.md`](subskills/dart/INDEX.md) to activate Dart analyzer rules, package versioning, and changelog subskills. |\n\n---\n\n### Step 4: Progressively Load Activated Subskills\n\nRead only the cross-language subskills activated in Step 2 and the language-specific subskills selected through Step 3 to evaluate your code against their rationales, checklists, and examples without loading unrelated language rules into context.\n",".agents/skills/pr-hygiene/SKILL.md":"# pr-hygiene\n\nPath: `.agents/skills/pr-hygiene/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/pr-hygiene/SKILL.md)",".agents/skills/update-changelog/SKILL.md":"# update-changelog\n\nPath: `.agents/skills/update-changelog/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/update-changelog/SKILL.md)","blueprints/skills/a2ui-blueprint-compliance/SKILL.md":"# a2ui-blueprint-compliance\n\nPath: `blueprints/skills/a2ui-blueprint-compliance/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/blueprints/skills/a2ui-blueprint-compliance/SKILL.md)","blueprints/skills/a2ui-blueprint-maintenance/SKILL.md":"# a2ui-blueprint-maintenance\n\nPath: `blueprints/skills/a2ui-blueprint-maintenance/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/blueprints/skills/a2ui-blueprint-maintenance/SKILL.md)","blueprints/skills/a2ui-blueprint-navigator/SKILL.md":"# a2ui-blueprint-navigator\n\nPath: `blueprints/skills/a2ui-blueprint-navigator/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/blueprints/skills/a2ui-blueprint-navigator/SKILL.md)","blueprints/skills/a2ui-create-feature-blueprint/SKILL.md":"# a2ui-create-feature-blueprint\n\nPath: `blueprints/skills/a2ui-create-feature-blueprint/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/blueprints/skills/a2ui-create-feature-blueprint/SKILL.md)","blueprints/skills/a2ui-implement-feature-from-blueprint/SKILL.md":"# a2ui-implement-feature-from-blueprint\n\nPath: `blueprints/skills/a2ui-implement-feature-from-blueprint/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/blueprints/skills/a2ui-implement-feature-from-blueprint/SKILL.md)","conformance/test_data/skills/express_basic_catalog.skill.md":"# Skills Skill\n\nPath: `conformance/test_data/skills/express_basic_catalog.skill.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/conformance/test_data/skills/express_basic_catalog.skill.md)","conformance/test_data/skills/express_basic_monolithic.skill.md":"# Skills Skill\n\nPath: `conformance/test_data/skills/express_basic_monolithic.skill.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/conformance/test_data/skills/express_basic_monolithic.skill.md)","conformance/test_data/skills/express_core.skill.md":"# Skills Skill\n\nPath: `conformance/test_data/skills/express_core.skill.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/conformance/test_data/skills/express_core.skill.md)","conformance/test_data/skills/fake_monolithic.skill.md":"# Skills Skill\n\nPath: `conformance/test_data/skills/fake_monolithic.skill.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/conformance/test_data/skills/fake_monolithic.skill.md)","eval/iterative_format_optimizer/skills/inference-format-optimizer/SKILL.md":"# inference-format-optimizer\n\nPath: `eval/iterative_format_optimizer/skills/inference-format-optimizer/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/iterative_format_optimizer/skills/inference-format-optimizer/SKILL.md)","AGENTS.md":"# AI Agent Protocol & Instructions\n\nPath: `AGENTS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/AGENTS.md)",".gemini/GEMINI.md":"# .gemini - Gemini Agent & Antigravity Instructions\n\nPath: `.gemini/GEMINI.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.gemini/GEMINI.md)","eval/DESIGN.md":"# eval - UI Design System & Style Tokens\n\nPath: `eval/DESIGN.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/DESIGN.md)","swift/AGENTS.md":"# swift - AI Agent Protocol & Instructions\n\nPath: `swift/AGENTS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/swift/AGENTS.md)","tools/build_catalog/README.md":"# build_catalog Documentation\n\nPath: `tools/build_catalog/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/README.md)","tools/composer/AGENTS.md":"# Composer Skill\n\nPath: `tools/composer/AGENTS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/AGENTS.md)","tools/composer/README.md":"# composer Documentation\n\nPath: `tools/composer/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/README.md)","tools/composer/components.json":"# Composer Skill\n\nPath: `tools/composer/components.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/components.json)","tools/composer/package.json":"# Composer Skill\n\nPath: `tools/composer/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/package.json)","tools/composer/tsconfig.json":"# Composer Skill\n\nPath: `tools/composer/tsconfig.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/tsconfig.json)","tools/editor/README.md":"# editor Documentation\n\nPath: `tools/editor/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/editor/README.md)","tools/editor/package.json":"# Editor Skill\n\nPath: `tools/editor/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/editor/package.json)","tools/editor/tsconfig.json":"# Editor Skill\n\nPath: `tools/editor/tsconfig.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/editor/tsconfig.json)","tools/inspector/README.md":"# inspector Documentation\n\nPath: `tools/inspector/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/inspector/README.md)","tools/inspector/package.json":"# Inspector Skill\n\nPath: `tools/inspector/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/inspector/package.json)","tools/inspector/tsconfig.json":"# Inspector Skill\n\nPath: `tools/inspector/tsconfig.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/inspector/tsconfig.json)",".agents/skills/a2ui-issue-triage/README.md":"# A2ui-issue-triage Skill\n\nPath: `.agents/skills/a2ui-issue-triage/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/a2ui-issue-triage/README.md)","conformance/extensions/a2a/a2a_integration.yaml":"# A2a Skill\n\nPath: `conformance/extensions/a2a/a2a_integration.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/conformance/extensions/a2a/a2a_integration.yaml)","conformance/extensions/adk/adk_extensions.yaml":"# Adk Skill\n\nPath: `conformance/extensions/adk/adk_extensions.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/conformance/extensions/adk/adk_extensions.yaml)","typescript/agents/a2ui_agent/CHANGELOG.md":"# Subagent: changelog\n\nPath: `typescript/agents/a2ui_agent/CHANGELOG.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/typescript/agents/a2ui_agent/CHANGELOG.md)","typescript/agents/a2ui_agent/KNOWN_GAPS.md":"# Subagent: known_gaps\n\nPath: `typescript/agents/a2ui_agent/KNOWN_GAPS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/typescript/agents/a2ui_agent/KNOWN_GAPS.md)","typescript/agents/a2ui_agent/README.md":"# Subagent: readme\n\nPath: `typescript/agents/a2ui_agent/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/typescript/agents/a2ui_agent/README.md)","typescript/agents/a2ui_agent/package.json":"# A2ui_agent Skill\n\nPath: `typescript/agents/a2ui_agent/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/typescript/agents/a2ui_agent/package.json)","typescript/agents/a2ui_agent/tsconfig.check.json":"# A2ui_agent Skill\n\nPath: `typescript/agents/a2ui_agent/tsconfig.check.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/typescript/agents/a2ui_agent/tsconfig.check.json)","typescript/agents/a2ui_agent/tsconfig.json":"# A2ui_agent Skill\n\nPath: `typescript/agents/a2ui_agent/tsconfig.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/typescript/agents/a2ui_agent/tsconfig.json)",".agents/skills/a2ui-audit/references/gh-reference.md":"# References Skill\n\nPath: `.agents/skills/a2ui-audit/references/gh-reference.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/a2ui-audit/references/gh-reference.md)",".agents/skills/a2ui-issue-triage/references/triage_criteria.md":"# References Skill\n\nPath: `.agents/skills/a2ui-issue-triage/references/triage_criteria.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/a2ui-issue-triage/references/triage_criteria.md)",".agents/skills/a2ui-remediate-problem/references/pr-description-template.md":"# References Skill\n\nPath: `.agents/skills/a2ui-remediate-problem/references/pr-description-template.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/a2ui-remediate-problem/references/pr-description-template.md)",".agents/skills/coding-principles/subskills/public-api-and-cross-framework-design.md":"# Subskills Skill\n\nPath: `.agents/skills/coding-principles/subskills/public-api-and-cross-framework-design.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/public-api-and-cross-framework-design.md)","tools/build_catalog/tests/fixtures/basic_catalog.json":"# Fixtures Skill\n\nPath: `tools/build_catalog/tests/fixtures/basic_catalog.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/tests/fixtures/basic_catalog.json)","tools/build_catalog/tests/fixtures/common_types.json":"# Fixtures Skill\n\nPath: `tools/build_catalog/tests/fixtures/common_types.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/tests/fixtures/common_types.json)","tools/build_catalog/tests/fixtures/component1.json":"# Fixtures Skill\n\nPath: `tools/build_catalog/tests/fixtures/component1.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/tests/fixtures/component1.json)","tools/build_catalog/tests/fixtures/component2.json":"# Fixtures Skill\n\nPath: `tools/build_catalog/tests/fixtures/component2.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/tests/fixtures/component2.json)","tools/build_catalog/tests/fixtures/component3.json":"# Fixtures Skill\n\nPath: `tools/build_catalog/tests/fixtures/component3.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/tests/fixtures/component3.json)","tools/build_catalog/tests/fixtures/v0_8_custom_catalog.json":"# Fixtures Skill\n\nPath: `tools/build_catalog/tests/fixtures/v0_8_custom_catalog.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/tests/fixtures/v0_8_custom_catalog.json)","tools/build_catalog/tests/fixtures/v0_8_standard_catalog_definition.json":"# Fixtures Skill\n\nPath: `tools/build_catalog/tests/fixtures/v0_8_standard_catalog_definition.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/tests/fixtures/v0_8_standard_catalog_definition.json)",".agents/skills/coding-principles/subskills/dart/INDEX.md":"# Dart Skill\n\nPath: `.agents/skills/coding-principles/subskills/dart/INDEX.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/dart/INDEX.md)",".agents/skills/coding-principles/subskills/dart/versioning-and-releases.md":"# Dart Skill\n\nPath: `.agents/skills/coding-principles/subskills/dart/versioning-and-releases.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/dart/versioning-and-releases.md)",".agents/skills/coding-principles/subskills/python/INDEX.md":"# Python Skill\n\nPath: `.agents/skills/coding-principles/subskills/python/INDEX.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/python/INDEX.md)",".agents/skills/coding-principles/subskills/python/architecture-and-facades.md":"# Python Skill\n\nPath: `.agents/skills/coding-principles/subskills/python/architecture-and-facades.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/python/architecture-and-facades.md)",".agents/skills/coding-principles/subskills/python/coding-standards-and-verification.md":"# Python Skill\n\nPath: `.agents/skills/coding-principles/subskills/python/coding-standards-and-verification.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/python/coding-standards-and-verification.md)",".agents/skills/coding-principles/subskills/swift/INDEX.md":"# Swift Skill\n\nPath: `.agents/skills/coding-principles/subskills/swift/INDEX.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/swift/INDEX.md)",".agents/skills/coding-principles/subskills/swift/coding-standards-and-testing.md":"# Swift Skill\n\nPath: `.agents/skills/coding-principles/subskills/swift/coding-standards-and-testing.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/swift/coding-standards-and-testing.md)",".agents/skills/coding-principles/subskills/typescript/INDEX.md":"# Typescript Skill\n\nPath: `.agents/skills/coding-principles/subskills/typescript/INDEX.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/INDEX.md)",".agents/skills/coding-principles/subskills/typescript/accessibility-semantics.md":"# Typescript Skill\n\nPath: `.agents/skills/coding-principles/subskills/typescript/accessibility-semantics.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/accessibility-semantics.md)",".agents/skills/coding-principles/subskills/typescript/css-theming-styling.md":"# Typescript Skill\n\nPath: `.agents/skills/coding-principles/subskills/typescript/css-theming-styling.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/css-theming-styling.md)",".agents/skills/coding-principles/subskills/typescript/reactive-lifecycle-performance.md":"# Typescript Skill\n\nPath: `.agents/skills/coding-principles/subskills/typescript/reactive-lifecycle-performance.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/reactive-lifecycle-performance.md)",".agents/skills/coding-principles/subskills/typescript/testing-isolation.md":"# Typescript Skill\n\nPath: `.agents/skills/coding-principles/subskills/typescript/testing-isolation.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/testing-isolation.md)",".agents/skills/coding-principles/subskills/typescript/typescript-closure-compiler.md":"# Typescript Skill\n\nPath: `.agents/skills/coding-principles/subskills/typescript/typescript-closure-compiler.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/typescript-closure-compiler.md)","blueprints/codebases/typescript/agents/a2ui_agent/codebase.blueprint.md":"# Subagent: codebase.blueprint\n\nPath: `blueprints/codebases/typescript/agents/a2ui_agent/codebase.blueprint.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/blueprints/codebases/typescript/agents/a2ui_agent/codebase.blueprint.md)","eval/iterative_format_optimizer/skills/inference-format-optimizer/references/agent_instructions.md":"# References Skill\n\nPath: `eval/iterative_format_optimizer/skills/inference-format-optimizer/references/agent_instructions.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/iterative_format_optimizer/skills/inference-format-optimizer/references/agent_instructions.md)","eval/iterative_format_optimizer/skills/inference-format-optimizer/references/inference_format_iteration.md":"# References Skill\n\nPath: `eval/iterative_format_optimizer/skills/inference-format-optimizer/references/inference_format_iteration.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/iterative_format_optimizer/skills/inference-format-optimizer/references/inference_format_iteration.md)","eval/iterative_format_optimizer/skills/inference-format-optimizer/references/scoring_model.md":"# References Skill\n\nPath: `eval/iterative_format_optimizer/skills/inference-format-optimizer/references/scoring_model.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/iterative_format_optimizer/skills/inference-format-optimizer/references/scoring_model.md)","eval/iterative_format_optimizer/skills/inference-format-optimizer/references/subagent_protocol.md":"# References Skill\n\nPath: `eval/iterative_format_optimizer/skills/inference-format-optimizer/references/subagent_protocol.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/iterative_format_optimizer/skills/inference-format-optimizer/references/subagent_protocol.md)","eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/README.md":"# Scripts Skill\n\nPath: `eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/README.md)","eval/iterative_format_optimizer/skills/inference-format-optimizer/templates/subagent_prompt.md":"# Templates Skill\n\nPath: `eval/iterative_format_optimizer/skills/inference-format-optimizer/templates/subagent_prompt.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/iterative_format_optimizer/skills/inference-format-optimizer/templates/subagent_prompt.md)","specification/v1_0/extensions/a2a/docs/a2ui_extension_specification.md":"# Docs Skill\n\nPath: `specification/v1_0/extensions/a2a/docs/a2ui_extension_specification.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/specification/v1_0/extensions/a2a/docs/a2ui_extension_specification.md)","tools/composer/src/data/theater/booking-form.json":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/booking-form.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/booking-form.json)","tools/composer/src/data/theater/component-gallery-stream.json":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/component-gallery-stream.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/component-gallery-stream.json)","tools/composer/src/data/theater/contact-card.json":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/contact-card.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/contact-card.json)","tools/composer/src/data/theater/flight-status.json":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/flight-status.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/flight-status.json)","tools/composer/src/data/theater/floor-plan.json":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/floor-plan.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/floor-plan.json)","tools/composer/src/data/theater/kitchen-sink.json":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/kitchen-sink.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/kitchen-sink.json)","tools/composer/src/data/theater/northstar-tour.json":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/northstar-tour.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/northstar-tour.json)","tools/composer/src/data/theater/org-chart.json":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/org-chart.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/org-chart.json)","tools/composer/src/data/theater/restaurant-booking.json":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/restaurant-booking.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/restaurant-booking.json)","tools/composer/src/data/theater/restaurant-confirmation.json":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/restaurant-confirmation.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/restaurant-confirmation.json)","tools/composer/src/data/theater/restaurant-finder.json":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/restaurant-finder.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/restaurant-finder.json)","tools/composer/src/data/theater/restaurant-grid.json":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/restaurant-grid.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/restaurant-grid.json)","tools/composer/src/data/theater/rizzcharts-chart.json":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/rizzcharts-chart.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/rizzcharts-chart.json)","tools/composer/src/data/theater/weather-widget.json":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/weather-widget.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/weather-widget.json)",".agents/skills/coding-principles/subskills/typescript/references/inspecting-typescript-public-api.md":"# References Skill\n\nPath: `.agents/skills/coding-principles/subskills/typescript/references/inspecting-typescript-public-api.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/references/inspecting-typescript-public-api.md)"},"files":{".agents/skills/a2ui-doc-sync-check/SKILL.md":"---\nname: a2ui-doc-sync-check\ndescription: Auditing codebase implementations for synchronization drift with the user documentation, readmes, and code comments.\n---\n\n# A2UI Code and Documentation Synchronization Check Skill\n\nThis skill guides the process of auditing concrete codebase implementations to verify that they are synchronized with their respective documentation files, codebase READMEs, and inline code comments/docstrings.\n\n---\n\n## **Instructions**\n\n1. **Locate Documentation and Readmes**:\n - Find all user guides, tutorials, and specifications under `docs/` and `specification/`.\n - Find the `README.md` files in each codebase directory.\n\n2. **Audit Readme Commands and Configs**:\n - For each codebase directory, parse the `README.md` to extract setup commands, dependencies, build/test commands, and directory layouts.\n - Cross-reference these details with the codebase's project files (e.g. `package.json`, `pyproject.toml`, `pubspec.yaml`, `Package.swift`).\n - If any command listed in the readme is invalid, deprecated, or has wrong arguments, list it as a discrepancy.\n\n3. **Audit Code-vs-Docs Public API and Settings**:\n - Make sure the glossary is respected. Verify that terms used in code, documentation and blueprints are consistent with [the glossary](../../../docs/public/concepts/glossary.md). If you find deviations, suggest fixes. If you see an important term is used in documentation and/or API, but is missing from the glossary, suggest an update for the glossary.\n - Inspect the codebase's public API entrypoints (classes, interfaces, types, methods).\n - Compare them against any descriptions, structural maps, or code snippets in the `docs/` folder.\n - Look for renamed classes, changed signatures, or removed options that are still described in the docs.\n - If the codebase exposes new settings or flags that are undocumented in `docs/` or the spec guides, log them as missing documentation.\n\n4. **Audit Inline Comments and Docstrings**:\n - Audit inline comments and docstrings (e.g. JSDoc in TS, docstrings in Python, triple-slash comments in Dart/Swift) for public APIs.\n - Flag any mismatch where code parameter names, types, return behaviors, or exceptions thrown deviate from what the docstring claims.\n\n5. **Links and Duplicates**:\n - When an artifact (code, document, issue, PR, comment and so on) is referenced, make sure it has a link.\n - When a glossary term is used - link the first occurrence of the term to the glossary entry if it exists.\n - Make sure there is no duplications of content. If you find some, delete the duplicate and leave a reference.\n\n6. **Conciseness and Clarity**:\n - Verify that documentation and code comments follow the [natural-writing](../natural-writing/SKILL.md) skill, and flag text that breaks its rules.\n\n7. **Format the Report**:\n - Build a Markdown report summarizing the findings:\n - Table of audited directories.\n - **Documentation Drift**: Mismatches between documentation guides (`docs/`) and codebase implementations.\n - **Readme Errors**: Invalid setup, compile, or test commands found in `README.md` files.\n - **Docstring Mismatches**: Outdated parameter names or behaviors described in inline comments.\n - Return this Markdown report as your final response.\n",".agents/skills/a2ui-audit/SKILL.md":"---\nname: a2ui-audit\ndescription: Main coordination skill to run the blueprint compliance, documentation synchronization, and test quality audits, posting the combined results as a labeled GitHub issue.\n---\n\n# A2UI Compliance Verification Skill\n\nThis skill coordinates the execution of specification compliance, documentation\nsync, and test quality audits, and publishes the combined results as a GitHub issue.\n\nOther than writing a report and creating an issue, this skill is purely a\nread-only skill; no changes are to be made to the codebase. Do not attempt to\nfix issues.\n\n---\n\n## **Instructions**\n\n1. **Audit Codebase Blueprint Compliance**:\n - Execute `python3 blueprints/skills/a2ui-blueprint-compliance/scripts/check_compliance.py` to dynamically discover all 8 production codebases and generate the baseline Markdown status report.\n - Run the sub-skill [`a2ui-blueprint-compliance`](../../../blueprints/skills/a2ui-blueprint-compliance/SKILL.md) to audit each discovered codebase for missing features or blueprint drift.\n - Save the compiled Markdown report to a temporary file in the workspace (e.g., `compliance_report.md`) under the header `## Codebase Blueprint Compliance Audit`.\n\n2. **Audit Code vs. Documentation Synchronization**:\n - Run the sub-skill [`a2ui-doc-sync-check`](../a2ui-doc-sync-check/SKILL.md) to audit documentation drift across `docs/`, `specification/`, codebase READMEs, and inline docstrings.\n - Append the returned Markdown report to `compliance_report.md` under a new header `## Code & Documentation Sync Audit`.\n\n3. **Audit Test Quality & Assertion Strength**:\n - Run the sub-skill [`a2ui-test-quality-check`](../a2ui-test-quality-check/SKILL.md) to audit test suites across all codebases for weak assertions and behavioral verification.\n - Append the returned Markdown report to `compliance_report.md` under a new header `## Test Quality & Assertions Audit`.\n\n4. **Summarize the report**:\n - Add a `## Summary` section at the top of the `compliance_report.md` file with a detailed overview of the audit scope and key findings across all audited codebases.\n - Add a `## Recommendations` section listing actionable, prioritized follow-up items formatted as a numbered list (e.g. `1. **P0**: ...`). Each numbered item MUST represent a concrete, self-contained remediation task.\n - Immediately below the recommendations list, include the mandatory automated remediation callout:\n > 🤖 **Automated Remediation**: Comment `/fix ` (e.g., `/fix 1`) on this issue to have an agent create a draft PR for that recommendation.\n\n5. **Format and Detail Requirements**:\n - **MANDATORY COMPLETE REPOSITORY COVERAGE**: The report MUST include status rows and detailed findings for **ALL 8 production codebases** discovered by `check_compliance.py`. Do NOT truncate, shortcut, or abbreviate the summary tables or detailed findings.\n - For each audit section, provide specific evidence:\n - Exact file paths (e.g. `python/a2ui_agent/transport.py:L45-L60`).\n - Specific function/class names, parameter mismatches, or missing feature descriptions.\n - Concrete examples of weak assertions (e.g. `assert response is not None` in `eval/tests/test_strategies.py`).\n - Follow the structure provided in the **Report Format Template** below.\n\n6. **Publish Report**:\n - Execute the local Python helper script to create the GitHub issue containing the combined reports:\n ```bash\n python3 .agents/skills/a2ui-audit/scripts/create_compliance_report.py compliance_report.md --repo a2ui-project/a2ui\n ```\n - The publishing script will create the GitHub issue, automatically inject copyable remediation prompt blocks referencing the newly created issue URL under each recommendation item, and update the issue body.\n - Ensure the helper script runs successfully.\n - Clean up the temporary file `compliance_report.md` after completion.\n\n---\n\n## **Report Format Template**\n\nWhen compiling `compliance_report.md`, use the following structure:\n\n```markdown\n## Summary\n\n[Provide a 2-3 paragraph detailed summary explaining the repository state, key areas audited across SDKs, renderers, and tests, and major findings.]\n\n## Recommendations\n\n1. **[Priority]**: **[Title]**\n - [Clear detailed explanation of the fix needed, specifying affected directories or modules.]\n\n2. **[Priority]**: **[Title]**\n - [Clear detailed explanation of the fix needed, specifying affected directories or modules.]\n\n## Codebase Blueprint Compliance Audit\n\n| Codebase Implementation | Associated Module | Status | Commits Behind | Current Commit | Latest Commit |\n| ----------------------- | ------------------- | ------ | -------------- | -------------- | ------------- |\n| `path/to/codebase` | `associated_module` | Status | X | `commit_hash` | `latest_hash` |\n\n### Detailed Findings & Discrepancies\n\n- **[Codebase Path]**: [Detailed description of missing specifications, missing required features, or frontmatter commit hash drift.]\n\n## Code & Documentation Sync Audit\n\n| Directory | Status | Identified Issues |\n| ------------- | ------ | ----------------- |\n| `path/to/dir` | Status | Brief Summary |\n\n### Detailed Findings\n\n- **README Mismatches**:\n - `path/to/README.md`: [Exact invalid command or outdated setup step found in README.]\n- **Docstring / API Drift**:\n - `path/to/file.ext:L12-L34`: [Specific parameter or return type mismatch between implementation and docstring/comments.]\n\n## Test Quality & Assertions Audit\n\n| Suite / Module | Status | Observations |\n| --------------- | ------ | ------------- |\n| `path/to/tests` | Status | Brief Summary |\n\n### Detailed Findings\n\n- **Weak Assertions**:\n - `path/to/test_file.ext` (`test_function_name`): [Explanation of weak assertion, e.g. using `assertNotNull` instead of schema/type check.]\n- **Missing Edge Case Tests**:\n - `path/to/module`: [Boundary conditions, error cases, or invalid inputs that lack test coverage.]\n```\n\n---\n\n## **References**\n\n- Refer to the [`a2ui-blueprint-compliance`](../../../blueprints/skills/a2ui-blueprint-compliance/SKILL.md) skill for codebase blueprint checking.\n- Refer to the [`a2ui-doc-sync-check`](../a2ui-doc-sync-check/SKILL.md) skill for documentation sync checking.\n- Refer to the [`a2ui-test-quality-check`](../a2ui-test-quality-check/SKILL.md) skill for test quality and assertion checking.\n- Refer to the [`gh-reference`](./references/gh-reference.md) reference for GitHub CLI (`gh`) operations.\n",".agents/skills/a2ui-implement-new-sdks-for-client-language/SKILL.md":"---\nname: a2ui-implement-new-sdks-for-client-language\ndescription: Step-by-step phased instructions for building new A2UI Core SDKs, Framework Adapters, and Inference SDKs from scratch in any client language.\n---\n\n# A2UI SDK Implementation Guide (Phased Execution)\n\nThis skill provides expert instructions and sequences for AI agents or contributors tasked with implementing A2UI Core SDKs, Framework Adapters, or Agent/Inference SDKs in a new programming language or UI framework.\n\n---\n\n## **1. Core State SDK Phases**\n\nIf you are building a new **Core SDK** (e.g., in Rust, Swift, Go, or C++), you must follow this sequence of phases:\n\n### **Phase 1: Context & Schemas Ingestion**\n\nThoroughly review:\n\n- `blueprints/modules/a2ui_core.blueprint.md` (for state and message structures).\n- `specification/v1_0/json/common_types.json` (dynamic binding schemas).\n- `specification/v1_0/json/server_to_client.json` (message envelopes).\n- `catalogs/basic/v1/catalog.json` (target components catalog).\n\n### **Phase 2: Technical Architecture Planning**\n\nCreate a detailed, local architectural proposal detailing:\n\n- **Dependencies**: Which Schema library and Observable/Reactive library will you use? Note that the reactive library must support both discrete event subscription and stateful, signal-like data streams (e.g., BehaviorSubject/Signal).\n- **Component APIs**: How will you define the `ComponentApi` interface in this language?\n- **Binding Strategy**: How will you structure the abstract Core Binder Layer?\n- _STOP and obtain human reviewer approval on this plan before writing code._\n\n### **Phase 3: Core Model Layer**\n\nImplement the framework-agnostic data and processor layers:\n\n1. **Observables & Signals**: Implement multi-cast reactive streams with clear unsubscribe mechanism to prevent leaks.\n2. **Protocol Structures**: Create strictly-typed native classes/structs representing `A2uiMessage` envelopes and client capabilities with serialization/deserialization.\n3. **DataModel & JSON Pointers**: Implement relative/absolute path resolution, auto-vivification (auto-typing intermediate segments), and bubble/cascade path change notifications.\n4. **Core State Models**: Implement `ComponentModel`, `SurfaceComponentsModel`, `SurfaceModel`, and `SurfaceGroupModel`.\n5. **Context Mapping**: Implement `DataContext` and `ComponentContext`.\n6. **MessageProcessor**: Ingest incoming messages and mutate the state models. Generate `inlineCatalogs` client capabilities.\n7. **Verification**: Write comprehensive unit tests for pointer cascading, JSON deserialization/validation, and message dispatching.\n\n### **Phase 4: Foundational Basic Catalog Support**\n\nBootstrap support for the Basic Catalog:\n\n- **Foundational Components**: Define the pure API schemas and Binders for: `Text`, `Row`, `Column`, `Button`, and `TextField`.\n- **Foundational Functions**: Implement `formatString` to interpret `${expression}` syntaxes, supporting recursive token evaluations and reactive coercion.\n- **Verification**: Ensure properties update reactively when underlying data paths emit notifications.\n\n### **Phase 5: Complete Basic Catalog Support**\n\n- **Full Components & Binders**: Define core binders for all other components in `basic/catalog.json`.\n- **Full Functions**: Implement remaining basic mathematical, logical, and array operations.\n- **Validation**: Ensure strict type coercion rules are satisfied and memory disposals work flawlessly.\n\n---\n\n## **2. Framework Adapter SDK Phases**\n\nIf you are building a new **UI Framework Adapter / Renderer** (e.g., in Flutter/Dart, SwiftUI, Jetpack Compose, Vue, or Svelte), follow this sequence:\n\n### **Phase 1: Ingestion & Core Integration**\n\nReview:\n\n- `blueprints/modules/a2ui_framework_adapter.blueprint.md` (View and rendering architecture).\n- `catalogs/basic/v1/basic_catalog_implementation_guide.md` (spacing, alignment, and typography specifications).\n\n### **Phase 2: Architectural Plan**\n\nDraft a plan specifying:\n\n- **Component Registry**: How components are dynamically resolved and instantiated.\n- **Surface Widget**: How the root canvas mounts and recurses through the layout tree starting at `root`.\n- **Observer/State Bridge**: Which Strategy (Direct, Predefined Binders, or Automated wrappers) will connect core signals to native views.\n- _STOP and obtain human reviewer approval on this plan._\n\n### **Phase 3: Adapter & Lifecycle Layer**\n\n- Implement `ComponentImplementation` base traits/classes.\n- Implement the framework-native `Surface` entrypoint widget.\n- Implement subscription management: lazy-subscribing only on mount, handling path stability updates, and strictly calling `dispose()` on unmount.\n\n### **Phase 4: Bootstrapping Basic Catalog Rendering**\n\n- Build native visual elements for: `Text`, `Row`, `Column`, `Button`, and `TextField`.\n- Bundle these elements into the first framework catalog adapter.\n- Verify reactive layout properties dynamically.\n\n### **Phase 5: Gallery Application Milestone**\n\nBuild the **Gallery App** as a testing playground with:\n\n- Left Column: Sample navigation.\n- Center Column: Surface preview, JSON message stream, and step-by-step interactive message stepper.\n- Right Column: Live data model inspect pane and action logger.\n- Load the 5 foundational verification examples: `00_simple-text.json`, `00_row-layout.json`, `00_complex-layout.json`, `00_interactive-button.json`, and `00_simple-login-form.json`.\n- _STOP and obtain human reviewer approval of the UI and visual rendering performance._\n\n### **Phase 6: Full Catalog Support**\n\n- Implement all remaining widgets (e.g. Card, Image, List, etc.) and validation traits like `Checkable`.\n- Update the Gallery App to support all official examples in `catalogs/basic/v1/examples/`.\n- Run visual parity and event action tests to verify correctness.\n",".agents/skills/a2ui-issue-triage/SKILL.md":"---\nname: a2ui-issue-triage\ndescription: Automates the triage of GitHub issues in the A2UI repository. Helps the oncall engineer by fetching untriaged issues, generating AI-suggested priorities, assignees, and responses, launching a local review dashboard, and bulk-applying approved decisions to GitHub. Use when tasked with triaging new GitHub issues or managing the repository backlog.\n---\n\n# A2UI GitHub Issue Triage Skill\n\nThis skill guides the process of fetching, analyzing, reviewing, and applying triage decisions to GitHub issues in the A2UI repository using a local interactive dashboard.\n\n> [!IMPORTANT]\n> **WRITING GUIDELINES**\n> When drafting replies, explanations, or any prose, refer to the [natural-writing](../natural-writing/SKILL.md) skill to ensure clarity, accuracy, and tone.\n\n---\n\n## Workflow\n\nFollow these steps to triage new or backlog issues:\n\n### Step 1: Fetch Untriaged Issues\n\nUse the fetch script to retrieve all open issues lacking a priority label (`P0`, `P1`, `P2`, `P3`, `P4`) in the A2UI repository.\n\n1. Run the fetch script to download the issues to a raw JSON file in your conversation-specific scratch directory:\n `python3 .agents/skills/a2ui-issue-triage/scripts/fetch_issues.py --repo \"a2ui-project/a2ui\" --output-file \"/brain//scratch/raw_issues.json\"`\n\n---\n\n### Step 2: Analyze and Suggest Triage\n\nProcess the raw issues and generate recommended triage fields based on the project's triage criteria.\n\n1. Read the triage criteria reference document: [triage_criteria.md](references/triage_criteria.md) and repository canonical templates: [triage-templates.md](../../../docs/contributing/triage-templates.md).\n2. For each issue in `raw_issues.json`, evaluate its description and comments to determine:\n - **Priority**: `P0` (Urgent), `P1` (High), `P2` (Medium), `P3` (Low), `P4` (Unplanned/Out of Scope), or `None`. `P0` and `P1` require assignees.\n - **Assignee**: Recommended owner based on the affected component or area.\n - **Action**: `investigate`, `assign_and_fix`, `needs_info`, `backlog`, `close_duplicate`, `close_invalid`, or `close_resolved`.\n - **Labels**: Applicable repository labels (e.g. `type: bug`, `component: lit renderer`, `status: first-line-handled`, `status: waiting-for-author-response`).\n - **Reply**: A polite, structured draft response addressing the author using canonical templates.\n3. If an issue is a potential duplicate, perform at most three targeted GitHub searches to find matching canonical issues before suggesting `close_duplicate`.\n4. **Natively Orchestrate Subagents**: Instead of running a Python script to spawn subagents (which can fail due to local workstation gRPC credential policies), the parent agent should natively orchestrate the parallel evaluations:\n - Load the first N issues (defaulting to 10, or as requested) from `raw_issues.json`.\n - Call the `invoke_subagent` tool in parallel for those issues. Prompt each subagent to analyze its assigned issue against the guidelines in [triage_criteria.md](references/triage_criteria.md) and return a structured JSON block containing `priority`, `action`, `labels`, and `reply`.\n - Once all subagents report back, compile their recommendations into the standard schema:\n - Map component labels to suggested assignees using git log history if necessary, and include a short sentence in `assignee_reason` explaining why they were chosen (e.g., \"Suggesting gspencer because they recently modified related code\").\n - Inject `total_issues_count` (preserving the total count from the raw issues JSON).\n - Save the final compiled payload to `issues_to_triage.json` in the scratch directory.\n\n---\n\n### Step 3: Launch Review Dashboard\n\nLaunch the interactive web dashboard to allow the oncall engineer to review and refine the suggested triages.\n\n1. Start the local server as a background task, pointing it to your scratch directory:\n `python3 .agents/skills/a2ui-issue-triage/scripts/launch_dashboard.py --data-file \"/brain//scratch/issues_to_triage.json\" --output-file \"/brain//scratch/triage_decisions.json\"`\n Set `WaitMsBeforeAsync` to `1000` so the server runs in the background.\n2. **Wait for Completion**: Stop calling tools and go idle. The launcher will automatically open the browser for the user and block until they click \"Apply Triages\" or \"Abort\". Once the user acts, the background task will complete, and you will receive a notification with the exit status.\n3. **Verify Exit Status**:\n - If the task exited with status `0` (approved), proceed to apply the decisions.\n - If the task exited with a non-zero status (abort), don't modify any issues. You MUST STOP and ask the user for further instructions.\n\n---\n\n### Step 4: Apply Decisions to GitHub\n\nOnce the dashboard task exits successfully, **Execute Approved Decisions**: Run the apply script to update the approved labels, assignees, and comments on GitHub:\n\n`python3 .agents/skills/a2ui-issue-triage/scripts/apply_triage.py --decisions-file \"/brain//scratch/triage_decisions.json\"`\n\n---\n\n## Bundled Resources\n\n- **[triage_criteria.md](references/triage_criteria.md)**: Authoritative guide for classifying issues, assigning priorities, and drafting response messages.\n- **`scripts/fetch_issues.py`**: Script to query open, untriaged issues via the GitHub CLI.\n- **`scripts/suggest_triage.py`**: Helper script to generate initial triage suggestions.\n- **`scripts/launch_dashboard.py`**: Local HTTP server that opens the interactive web dashboard in the user's browser.\n- **`assets/triage_dashboard.html`**: HTML/CSS/JS template for the triage review interface.\n- **`scripts/apply_triage.py`**: Script to apply finalized triage decisions to GitHub.\n",".agents/skills/a2ui-generate-pydantic-models/SKILL.md":"---\nname: a2ui-generate-pydantic-models\ndescription: Automated generator for strongly typed Pydantic v2 data models and basic catalogs across any A2UI protocol version (v0.8, v0.9, v0.9.1, v1.0, etc.).\n---\n\n# A2UI Pydantic Model Generation Skill\n\nThis skill provides an automated code generation tool that produces strongly typed Pydantic v2 data models and basic catalog definitions for `python/a2ui_core` directly from the schemas and catalogs in `specification//`.\n\n---\n\n## Agent Execution Steps\n\nWhen given a prompt like _\"Generate Pydantic model classes for A2UI spec v1.0\"_:\n\n1. **Extract the target version parameter from the prompt** (e.g. `v1.0` -> `v1.0`).\n\n2. **Execute the generator script exactly once for that target version**:\n\n ```bash\n uv run python .agents/skills/a2ui-generate-pydantic-models/scripts/codegen_pydantic.py --version \n ```\n\n _(Replace `` with the single requested version, e.g. `--version v1.0`)_.\n\n3. **Format generated Python code**:\n\n ```bash\n cd python/a2ui_core\n uv run pyink .\n ```\n\n4. **Verify the generated files** by running pytest:\n\n ```bash\n cd python/a2ui_core\n uv run pytest tests/test_codegen_pydantic.py\n ```\n\n5. **Stop and report completion to the user.**\n\n---\n\n## Generated Output Files per Version\n\nWhen executed for a target version `` (e.g. `v1.0` -> `v1_0`), the script generates:\n\n1. **`python/a2ui_core/src/a2ui/core/schema//`**:\n - `constants.py`\n - `common_types.py`: strongly typed shared models and the `COMMON_TYPES_DEFS` manifest, which maps each spec `$defs` name to its symbol in spec order. No spec schema is copied verbatim; the published common types schema is rebuilt from these symbols.\n - Type aliases such as `ComponentId`, `Child`, `ChildList` and the `Dynamic*` unions are registered as `Annotated[..., Field(description=...)]` with the spec descriptions, so the runtime JSON schema generator needs no per-def special cases. Dynamic unions list their members in spec order.\n - When a `Dynamic*` def constrains its function-call branch with a `returnType` const, the branch is `Annotated[FunctionCall, ReturnType(\"\")]`, which validates the return type and emits the spec's `allOf` in both modes. Any other branch shape fails generation.\n - Every model extends `SpecBaseModel` (hand-written in `schema/common_types.py`) and has no generated methods. Keywords that fields cannot produce are declared in the model config as `json_schema_extra=SchemaKeywords(...)`: it drops `additionalProperties` where the spec leaves it out and adds `returnType`, `unevaluatedProperties`, `title`, `allowedParents` and `oneOf` required-alternatives (see `_SPEC_KEYWORDS`). The keywords apply only to the declaring model, not to subclasses. `SpecBaseModel` validates a declared `oneOf` whose branches only list required fields (for example `FunctionResponse`'s `value`/`error`), requiring exactly one branch.\n - Only composition that references the catalog's function union is limited to `spec_schema()` (`SchemaKeywords(..., spec_only=True)`), which the published common types schema uses: v0.9's `FunctionCall` `oneOf`, v1.0's `FunctionCall` `allOf` over `FunctionCommon` and `anyFunction` (`replace=True`, since the spec def is pure composition), and v0.9's precise `args` shape (a schema-only `JsonSchemaAs` annotation requested through the `x-python-type` property override). Catalogs keep the flat model shape there. References inside declared keywords are the markers `def_ref(\"\")` and `catalog_functions()` from the internal `a2ui.core.schema._json_schema` module, which the schema builder resolves to `$ref`s. `FunctionCall` itself is a flat model that validates any call without the catalog.\n - Nested object properties with their own properties become helper models named `` (for example `ComponentCommonMetadata`, `IndexSystemFunctionArgs`, `FunctionResponseError`), which schemas inline. Wrapper unions such as `Action` are `TypeAliasType`s, so fields reference them by def name. Each branch gets a `Wrapper` model, and a branch property that is an object becomes `` (`ActionEvent`, `ActionEventWrapper`, `ActionFunctionCallWrapper`). A generated name that collides with a def, a base symbol or another helper fails generation.\n - A def that the spec leaves open (no `additionalProperties` and no `unevaluatedProperties: false`) allows extra keys. `ComponentCommon` is the exception (`_SUBCLASSED_DEFS`): generated catalog components subclass it and must stay closed.\n - Optional fields are typed `X | None` so they can be absent. `SpecBaseModel` rejects an explicit null for such a field unless `X` accepts null itself (`Any`), under both the spec name and the Python field name; it does not change the JSON schema. Catalog components inherit this rule through `ComponentCommon`. v0.9's `FunctionCall.args` also rejects null values.\n - Primitive defs such as `CallId` are `TypeAliasType`s, so local references keep their `$ref`. References from other documents to a primitive def map to its Python type through `_CROSS_DOCUMENT_REF_TYPES` in `engine.py`.\n - `patternProperties` objects (`Extensions`) are `TypeAliasType`s over a key-checking validator, and their pattern is published in the spec schema and in catalogs. Python's `re` cannot compile `\\p{...}`, so the SDK validates JSON schemas with `a2ui.core.validation.SchemaValidator` (powered by `regex`). The `DynamicValue` literal-object branch carries the spec's `propertyNames` and `not` clauses through a `SchemaKeywords` annotation in both modes.\n - Common types keep `component` properties (`Surface`) and emit required consts without defaults (`skip_component_property` and `required_const_default` on the engine). Spec defaults are emitted as JSON schema `default` values (`schema_defaults`), not as description notes.\n - Common types are generated in strict mode: a schema shape the models would not enforce (an unknown or non-local `$ref`, siblings next to `$ref`/`const`/composition, an unsupported keyword next to `properties`, a required property that is not declared, an empty union) raises instead of loosening validation. Output is deterministic and does not depend on string hashing.\n - `agent_to_renderer.py` / `server_to_client.py`: strongly typed outbound message models and the `AGENT_TO_RENDERER_DEFS` manifest, which maps each spec `$defs` (or v0.8 `properties`) name to its symbol in spec order so `get_agent_to_renderer_schema_map` / `get_agent_to_renderer_schema_json` can rebuild `server_to_client.json` / `agent_to_renderer.json` from the models. Nested payload objects and array item objects become helper models marked with `INLINE_DEF_MARKER` (for example `CreateSurfaceMetadata`, `SurfaceUpdateComponentsItem`), and non-message `$defs` (`Component`, `ComponentsList`) are emitted as `TypeAliasType`s with `SchemaKeywords`.\n - `renderer_to_agent.py` / `client_to_server.py`\n - `renderer_capabilities.py` / `client_capabilities.py`\n - `agent_capabilities.py` / `server_capabilities.py` (when present in spec)\n - `catalog_definition.py` (when present in spec)\n - `__init__.py`\n\n2. **`python/a2ui_core/src/a2ui/core/basic_catalog//`**:\n - `components.py` (strongly typed components & `ModelComponentApi` registrations)\n - `function_apis.py` (strongly typed function schemas & `FunctionApi` classes)\n - `styles.py` (theme schema, generated when theme is defined in catalog)\n - `__init__.py`\n - The models and the generated `BasicCatalog` carry everything `Catalog.to_json()` needs to rebuild the published catalog document from them, with no catalog JSON copied into Python or read at runtime:\n - `BasicCatalog` passes the document's top-level fields to `Catalog`: `$schema`, `$id`, `title`, `description`, `protocolVersion` (None when the document declares none), `catalogId` when it declares none, `instructions`, where it writes its theme (`theme_location`), its unions (`union_defs`, which must list the catalog's entries) and the document its common types references point into (`common_types_uri`). The theme is passed as `theme_model`.\n - Without common types (v0.8), nested objects become models that keep the document's shapes: two nested objects of different shapes never share a model (the later one is prefixed with its component or parent model, for example `SliderValueItem`), and their descriptions stay on the fields, with line breaks, rather than becoming docstrings. `Catalog.to_json()` writes them inline, as the v0.8 document does.\n - For versions with a common types schema (v0.9+), the models carry everything `Catalog.validation_schema` and `Catalog.to_json()` need to rebuild the specification's `catalog.json` shape from them:\n - A component's `allOf` references to common types defs (for example `Checkable`) become base classes, and catalog defs (`CatalogComponentCommon`) become base models. A component with more than one base sets `extra=\"forbid\"`, because Pydantic would otherwise inherit an open base's config. A component description becomes the class docstring and fails generation if it cannot be one.\n - A function's description becomes the `FunctionApi.description` attribute. Keywords on the `args` object that fields cannot produce (`unevaluatedProperties`, `additionalProperties`, required-alternative `anyOf`) are declared with `SchemaKeywords` as the model's `json_schema_extra`, and an unknown keyword fails generation.\n - Field constraints (`minItems`, `minimum`, ...) are emitted as `Field` arguments, so they are validated and published; `format` and `default` are published through `json_schema_extra`. An `allOf` member that only adds keywords becomes a `SpecAllOf` annotation.\n - The conformance cases `test_v08_basic_catalog_to_json`, `test_v09_basic_catalog_to_json` and `test_v10_basic_catalog_to_json`, and `python/a2ui_core/tests/test_basic_catalog_documents.py`, compare `BasicCatalog().to_json()` with the published files, so any drift fails the tests.\n\n3. **`python/a2ui_core/src/a2ui/core/schema/__init__.py`**:\n - Registers the version in `A2uiProtocolVersion` enum and updates envelope unions.\n",".agents/skills/a2ui-add-eval-datapoint/SKILL.md":"---\nname: a2ui-add-eval-datapoint\ndescription: Step-by-step workflow for adding and verifying new evaluation data points in the A2UI evaluation suite.\n---\n\n# Adding and verifying A2UI evaluation data points\n\nUse this skill when adding new data points or datasets to the A2UI evaluation framework in `eval/`.\n\n## References\n\nFor full architecture and setup details, consult:\n\n- `eval/CONTRIBUTING_USE_CASES.md`: The authoritative contributor guide for evaluation use cases, containing field definitions, context rules, and unencrypted multi-turn examples.\n- `eval/README.md`: Evaluation quickstart, Transcrypt setup, and CLI flags.\n- `eval/DESIGN.md`: Architecture, multi-stage scorers, and encryption-at-rest design.\n- `eval/datasets/dataset_schema.json`: Formal JSON Schema defining required fields and structural rules for evaluation data points.\n\n---\n\n## Step-by-step workflow\n\n### 1. Unlock Transcrypt\n\nDatasets in `eval/datasets/` are encrypted at rest. Unlock Transcrypt locally before authoring (ask an A2UI team member for the password):\n\n```bash\ncd eval\nbin/transcrypt -y -c aes-256-cbc -p \n```\n\n### 2. Author the data point\n\nCreate or update a dataset file in `eval/datasets/.yaml` (e.g. `eval/datasets/my_dataset.yaml`).\n\nEvery data point **must conform** to the JSON Schema in `eval/datasets/dataset_schema.json` and follow the authoring guidelines in `eval/CONTRIBUTING_USE_CASES.md`.\n\nFor a complete unencrypted reference example of a multi-turn conversation with system instructions, tool calls (including unrelated background tool calls), tool responses, and a judging target rubric, inspect `eval/examples/example_eval_case.json`.\n\n**Key authoring requirements from `eval/CONTRIBUTING_USE_CASES.md`:**\n\n- Include the full multi-turn conversation history (`messages`), including assistant function calls (`tool_calls`) and tool responses (`role: tool`). Do not use single-turn prompts.\n- Write the `target` as a qualitative judging rubric for the LLM-as-a-judge (what UI components must appear, data binding rules, and what errors to penalize). Do not include a hardcoded JSON string, as that ties the evaluation to a particular inference format.\n\n### 3. Validate schema compliance\n\nVerify that all data points satisfy `eval/datasets/dataset_schema.json`:\n\n```bash\ncd eval\nuv run python -m pytest tests/test_dataset.py\n```\n\n### 4. Run an evaluation on the new data point\n\nAlways execute an evaluation run on the newly added dataset to verify model inference and scoring:\n\n```bash\ncd eval\n# Quick validation on gemini-3.1-flash-lite\nuv run main.py --dataset my_dataset --sanity\n\n# Full evaluation check\nuv run main.py --dataset my_dataset\n```\n\nView the interactive traces and judging rationales:\n\n```bash\nuv run inspect view start\n```\n\n### 5. Verify encryption and commit\n\nWhen staging changes, Git applies the Transcrypt clean filter. Confirm that the staged file is encrypted ciphertext before committing:\n\n```bash\n# Stage the new dataset file\ngit add eval/datasets/my_dataset.yaml\n\n# Verify staged content is encrypted ciphertext (not plaintext)\ngit diff --cached eval/datasets/my_dataset.yaml\n\n# Commit the encrypted data point\ngit commit -m \"feat(eval): add my_dataset evaluation data points\"\n```\n",".agents/skills/a2ui-release-python/SKILL.md":"---\nname: a2ui-release-python\ndescription: Releases the Python SDKs (a2ui-core, a2ui-agent-sdk, a2ui-a2a, a2ui-adk) to PyPI by running preflight checks, dispatching the release workflow as a dry run, confirming with the maintainer, publishing, and following the changelog pull request through to merge. Use when asked to cut, publish, or release a Python SDK version.\n---\n\n# Releasing the A2UI Python SDKs\n\nThis skill turns a one-line request such as _\"release a2ui-core patch\"_ or\n_\"release the Python SDKs\"_ into the full release sequence.\n\nPublishing is done by the\n[Release Python SDKs](../../../.github/workflows/release-pypi.yml) workflow. This\nskill does not reimplement any of it. Its job is the part the workflow cannot do\nfor itself: choosing the bump, catching the problems that a workflow run would\ndiscover too late, and following through afterwards.\n\nBackground for anything not covered here:\n[docs/contributing/release.md](../../../docs/contributing/release.md).\n\n> [!CAUTION]\n> **Publishing to PyPI is irreversible.** A version can be yanked but never\n> reused or deleted. Step 5 is a mandatory stop. Never dispatch a run with\n> `dry_run: false` without an explicit go-ahead from the maintainer in the\n> current conversation.\n\n### What runs where\n\n**The workflow performs the release. Nothing here does.** Building, tagging,\npushing tags, staging in the Artifact Registry and triggering the Exit Gate all\nhappen inside `release-pypi.yml`, and only there. It could not be otherwise: the\nExit Gate authenticates by matching the OIDC claim\n`…/release-pypi.yml@refs/heads/main`, so a local upload has no credentials to\nuse.\n\n| Run locally | Run by the workflow |\n| :--------------------------------------------- | :------------------------------------------------ |\n| `release_version.py notes` | `release_version.py plan` (authoritative) |\n| `release_version.py plan` (preview only) | `release_version.py check` |\n| `release_version.py check` (preview only) | `release_version.py cut-changelog` |\n| `gh workflow run`, `gh run view`, `gh pr list` | `release_artifacts.py`, `confirm_pypi.py` |\n| | `uv build`, `twine upload`, `git tag`, `git push` |\n\nThe local calls are limited to the read-only subcommands `notes`, `next`,\n`current`, `tag`, `plan` and `check`. They exist to answer two questions before\nspending a CI run: is there anything to release, and will preflight reject it.\n\n> [!IMPORTANT]\n> A local `plan` is a **prediction**, not the release. It is computed from the\n> tags in the local checkout, so it is only as current as the last fetch — which\n> is why Step 2 fetches first. The plan the workflow computes is the one that\n> counts, and Step 4 reads it back out of the run before anyone approves it.\n\nNever run `cut-changelog --write`, `git tag`, `git push`, `uv build` or `twine`\nby hand to perform a release. If the workflow cannot do it, fix the workflow.\n\n> [!IMPORTANT]\n> One exception, and it is deliberate: **the changelog pull request has to be\n> opened by a person, not by the workflow.** GitHub does not start workflow runs\n> for events caused by `GITHUB_TOKEN`, so a pull request the workflow opened\n> would never get the required checks and could never be merged. The workflow\n> pushes the branch; Step 7 opens the pull request.\n\n## Step 1: Check environment prerequisites\n\nCheck that your local environment meets these prerequisites before proceeding.\nThe preflight check in Step 3 (`release_version.py check`) also validates these\nautomatically and stops with an `Action needed:` message for each one that\nfails. They are skipped in GitHub Actions, where they do not apply.\n\n1. **An a2ui checkout.** Run from your clone of `a2ui-project/a2ui`. The script\n finds the repository root itself, so a subdirectory works (it warns), but\n the commands below use paths relative to the root.\n2. **Python 3.11+.** The script reads `pyproject.toml` with the standard\n library `tomllib`. If your system `python3` is older, run it through the\n project toolchain instead: `uv run python .github/scripts/release_version.py\n...`.\n3. **GitHub CLI (`gh`)**, installed, authenticated with `github.com`, and with\n write access to `a2ui-project/a2ui`. It dispatches and watches the workflow\n and opens the changelog pull request.\n4. **Git identity.** `git config user.name` and `git config user.email` must be\n set, so the changelog commit and pull request pass CLA verification.\n5. **A remote that points at `a2ui-project/a2ui`.** It may be called `origin`\n in a direct clone or `upstream` beside a fork; the script finds it by URL.\n The commands below call it `${REMOTE}`:\n\n ```bash\n REMOTE=$(git remote -v | awk '/a2ui-project\\/a2ui(\\.git)?\\/? \\(fetch\\)/ {print $1; exit}')\n ```\n\n---\n\n## Step 2: Work out what is being released\n\nTwo things are needed: `PACKAGE` and `BUMP` (`patch`, `minor`, or `major`).\n`PACKAGE` names the packages to release, either as a comma-separated list of\npackage names or as `all`:\n\n- One package: `a2ui-agent-sdk`\n- Several packages: `a2ui-a2a,a2ui-adk`\n- Every package: `all` (`a2ui-core`, `a2ui-agent-sdk`, `a2ui-a2a`, `a2ui-adk`)\n\nThe workflow publishes the listed packages in dependency order (`a2ui-core`,\n`a2ui-agent-sdk`, `a2ui-a2a`, `a2ui-adk`), whatever order they are listed in.\nDerive `PACKAGE` and `BUMP` from the changelogs. Never infer them from the\nphrasing of the request.\n\nFetch first. Versions are derived from tags, so every number below is wrong if\nthe checkout is behind:\n\n```bash\ngit fetch \"${REMOTE}\" main --tags\n```\n\n```bash\nfor package in a2ui-core a2ui-agent-sdk a2ui-a2a a2ui-adk; do\n echo \"== ${package}\"\n python3 .github/scripts/release_version.py notes --package \"${package}\"\ndone\n```\n\n**Choose the packages.** Release only those with a non-empty `## Unreleased`.\nEmpty output means that package has nothing to release, whatever was asked for.\nA plural request such as _\"release the Python SDKs\"_ does not mean `all`. List\nexactly the packages with pending entries, for example\n`a2ui-agent-sdk,a2ui-a2a`. If only one has pending entries, that one is the\nrelease. If none does, stop and say so.\n\nCheck the exit status, not just the output. The two failure shapes are\ndifferent answers:\n\n| Result | Meaning | Do |\n| :------------------------- | :---------------------------------------------------------------- | :----------------------------------- |\n| exit 0, output | Entries pending | Release this package |\n| exit 0, no output | `## Unreleased` is empty | Skip this package |\n| exit 1, `error:` on stderr | Changelog is malformed, usually a missing `## Unreleased` heading | Stop. Report it and do not dispatch. |\n\n> [!NOTE]\n> Dispatching a package whose `## Unreleased` is empty is not dangerous, just wasteful. The\n> plan builds, then preflight rejects the empty package and the run fails\n> several minutes in. The check above costs a second.\n\n**Choose the bump.** Read the entries. Fixes only means `patch` and new\nfeatures mean `minor`. A breaking change means `minor` while the package is\nbelow 1.0, and `major` from 1.0 on. Preview the result with `plan`,\nwhich returns exactly what the workflow will compute — version, tag and release\nnotes for every selected package:\n\n```bash\npython3 .github/scripts/release_version.py plan --package \"${PACKAGE}\" --bump \"${BUMP}\"\n```\n\n> [!IMPORTANT]\n> **One run applies one bump level to every listed package.** The workflow\n> takes a single `bump` input, so `build_plan` raises every version by the same\n> amount. When the packages warrant different levels — say fixes in\n> `a2ui-core` and a feature in `a2ui-agent-sdk` — there is no single right\n> answer. Put the choice to the maintainer:\n>\n> - **Take the higher level for every listed package.** One release, one\n> changelog pull request. The cost is an over-bumped version on the quieter\n> packages.\n> - **Run one release per bump level.** Correct versioning, but the changelog\n> pull request from each run must be **merged before starting the next**, or\n> the Step 3 guard will block it. Release in dependency order: `a2ui-core`,\n> `a2ui-agent-sdk`, `a2ui-a2a`, `a2ui-adk`.\n\n> [!IMPORTANT]\n> **A minor or major `a2ui-core` bump may need a pin change first.**\n> `a2ui-agent-sdk` declares a range such as `a2ui-core>=0.3.0,<0.4.0` in\n> [a2ui_agent/pyproject.toml](../../../python/a2ui_agent/pyproject.toml). If\n> the proposed `a2ui-core` version falls outside it, widen the pin in its own\n> pull request and **merge it to `main` before dispatching**. The workflow\n> releases `main` as it is and cannot change package files during the run.\n> Step 3 rejects the release until this is done.\n>\n> The same applies down the chain: `a2ui-a2a` and `a2ui-adk` pin\n> `a2ui-agent-sdk` in their `pyproject.toml`, and `a2ui-adk` pins `a2ui-a2a`\n> in its `a2a` extra. A new version of a package must fall inside every pin on\n> it.\n\n> [!IMPORTANT]\n> **A dependent needs its dependencies on PyPI.** Releasing `a2ui-a2a` or\n> `a2ui-adk` on its own requires the released `a2ui-agent-sdk` (and, for\n> `a2ui-adk`, `a2ui-a2a`) to satisfy its pins already. If it does not, release\n> the dependency first, or list it in the same run. Step 3 reports\n> this as \"has not been released yet\" or \"requires ..., but the latest release\n> ... is ...\".\n>\n> **First release of a brand-new package.** A package with no tag yet starts\n> from `0.0.0`, so use a `minor` bump to release `0.1.0`. Before its first\n> release, the package name must be added to the OSS Exit Gate allowlist for\n> `a2ui/pypi` and registered as a **Pending Publisher** on\n> `https://pypi.org/manage/account/publishing/` under the **Google** tab with\n> email `a2ui-py@oss-exit-gate-prod.iam.gserviceaccount.com` and an empty\n> subject (see `go/a2ui-release#pypi`). PyPI indexes Google Cloud Pending\n> Publishers uniquely by `(email, sub)`, so **only one Pending Publisher can be\n> registered at a time**. Do not release two brand-new packages in the same\n> manifest: register and publish them one at a time so the first upload\n> promotes its Pending Publisher to a project-scoped Trusted Publisher before\n> registering the second.\n\nPut the proposal to the maintainer with `ask_question`, showing the pending\nentries and the resulting versions, and let them correct it.\n\n---\n\n## Step 3: Preflight locally\n\nThese checks cost seconds and catch the failures that are expensive to hit\nmid-run. Run all of them before dispatching anything.\n\n**1. The environment and the checkout.** `check` runs these for you (see\nStep 1: Check environment prerequisites); this is what it looks for and why:\n\n- **No outstanding changelog branch** from a previous release on `${REMOTE}`.\n Until the last release's changelog lands, its entries are still under\n `## Unreleased`, and this release would repeat them. It checks the branch,\n not the pull request, because the release stops at the branch and there may\n be no pull request yet. The repository deletes branches on merge, so no\n branch means the last changelog landed. If one is found, get that change\n merged (open the pull request if nobody has), then start over from Step 2,\n because the pending entries will have changed.\n- **The released packages match `${REMOTE}/main`.** The workflow builds from\n `main`, so `python/a2ui_core`, `python/a2ui_agent`, `python/a2ui_a2a` and\n `python/a2ui_adk` must be identical to it.\n Uncommitted edits, or a local commit that is not merged yet (a widened pin,\n say), would make the local preview describe a release that is not the one\n that will go out. Other paths in the checkout do not matter.\n\nIf it reports any of these, or any of the Environment Prerequisites, stop and\nsay what was found.\n\n**2. The repository's own preflight passes.** The package checks (changelog,\ntag, and pin) are the ones the workflow runs, so a failure in them here is a\nfailure there:\n\n```bash\n# Check using bump level (comma-separated package names, or 'all'):\npython3 .github/scripts/release_version.py check --package \"${PACKAGE}\" --bump \"${BUMP}\"\n\n# Or check a specific version directly (single package only):\npython3 .github/scripts/release_version.py check --package \"${PACKAGE}\" --version \"${VERSION}\"\n```\n\nIt rejects an empty `## Unreleased`, a version that already has a tag, a version\noutside the range that another package pins it to, and a dependency on another\npackage of this repository that no released version (or no version in the same\nrun) satisfies. With several packages and `--bump`, it evaluates every listed\npackage and their cross-dependency pins in a single step.\n\nIf preflight reports a pin problem, stop: see the pin notes in Step 2.\n\n---\n\n## Step 4: Dry run\n\nA dry run builds and stages the artifacts in the Exit Gate Artifact Registry,\nremoves them again, and pushes nothing.\n\n```bash\ngh workflow run release-pypi.yml --repo a2ui-project/a2ui --ref main \\\n -f package=\"${PACKAGE}\" -f bump=\"${BUMP}\" -f dry_run=true\n```\n\nWait a few seconds, then find the run and watch it:\n\n```bash\ngh run list --repo a2ui-project/a2ui --workflow=release-pypi.yml --limit 1 \\\n --json databaseId,status,url\ngh run watch \"${RUN_ID}\" --repo a2ui-project/a2ui --exit-status\n```\n\n> [!TIP]\n> Use the full `databaseId`. A truncated run ID returns 404.\n\nIf it fails, read the failing step's log and consult Troubleshooting below\nbefore retrying.\n\nWhen it passes, read back the plan the run actually computed. The dry run does\nnot upload the plan artifact, and step summaries are not available over the API,\nbut the plan step prints the JSON into the log:\n\n```bash\ngh run view \"${RUN_ID}\" --repo a2ui-project/a2ui --log \\\n | grep -A 20 'Build the release plan'\n```\n\nCompare it against the local `plan` output from Step 2. They are computed the\nsame way and should agree. If they differ, a tag landed in between — stop and\nwork out why before going any further.\n\n---\n\n## Step 5: Confirm with the maintainer\n\n**Stop here.** Show the maintainer:\n\n- the exact versions and tags from the dry run's plan,\n- the changelog entries that will become the release notes,\n- that the dry run passed.\n\nQuote the version numbers in full, for example `a2ui-agent-sdk 0.7.0`. Do not\ndescribe the release only as \"a minor bump\" — the bump level is the input, the\nversion is the irreversible consequence, and it is the version the maintainer\nneeds to approve.\n\nThen ask for explicit confirmation to publish. Proceed only on a clear yes.\n\n---\n\n## Step 6: Publish\n\n```bash\nAUTHOR_NAME=$(git config user.name)\nAUTHOR_EMAIL=$(git config user.email)\ngh workflow run release-pypi.yml --repo a2ui-project/a2ui --ref main \\\n -f package=\"${PACKAGE}\" -f bump=\"${BUMP}\" -f dry_run=false \\\n -f author_name=\"${AUTHOR_NAME}\" -f author_email=\"${AUTHOR_EMAIL}\"\n```\n\nWatch it as in Step 4. The run pushes the tags, stages the artifacts, uploads\nthe manifest that triggers the Exit Gate, and creates the GitHub releases.\n\nFour jobs follow:\n\n| Job | What it does | If it fails |\n| :---------- | :----------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- |\n| `build` | Runs tests and builds distributions | Test failure or malformed distribution. See Troubleshooting. |\n| `release` | Stages, tags, and triggers publishing | Real failure. See Troubleshooting. |\n| `confirm` | Polls PyPI, then links the GitHub releases | A timeout is not a failure. The hourly [Confirm PyPI publication](../../../.github/workflows/release-verify-pypi.yml) workflow finishes the job. |\n| `changelog` | Pushes the changelog branch | Publishing already succeeded. Cut the changelog by hand and open the PR yourself. |\n\n> [!IMPORTANT]\n> **The run stays active for several minutes after `release` goes green, and\n> that is normal.** Triggering the Exit Gate is not publishing. The Exit Gate\n> works asynchronously and reports only by email, so the `confirm` job sits and\n> polls PyPI every 30 seconds for up to 20 minutes waiting for the version to\n> appear.\n>\n> `gh run watch` blocks until all three jobs finish, so it is the wait. Let it\n> run. Do not poll PyPI in a loop alongside it, and do not report the release as\n> finished — or as failed — while `confirm` is still in progress.\n\n---\n\n## Step 7: Follow through\n\nA release is not done when the workflow goes green.\n\n1. **Confirm the version is live.** The waiting has already happened on the\n runner, so read the `confirm` job's outcome rather than starting a fresh\n wait:\n\n - **`confirm` succeeded** — the version is on PyPI and the GitHub releases\n have been updated with links. Verify once and move on:\n\n ```bash\n curl -s -o /dev/null -w '%{http_code}\\n' \"https://pypi.org/pypi/${PYPI_NAME}/${VERSION}/json\"\n ```\n\n `200` confirms it. A `404` here, after `confirm` reported success, is a CDN\n lag of a minute or two — wait briefly and check again.\n\n - **`confirm` timed out** — publishing took longer than 20 minutes. **This is\n not a failed release.** The artifacts are staged and the Exit Gate still\n has them. Do not re-run the release, and do not try to publish the version\n again: that would burn a version number. Tell the maintainer it is\n outstanding, and leave it to the hourly\n [Confirm PyPI publication](../../../.github/workflows/release-verify-pypi.yml)\n workflow, which finds the release by its pending marker and links it once\n PyPI catches up. The Exit Gate also emails\n `a2ui-core-working-group@google.com` with the outcome either way.\n\n - **`confirm` failed for another reason** — read the log. The publish itself\n may still have succeeded, so check PyPI before concluding anything.\n\n2. **Open the changelog pull request and get it merged.** The release pushed the\n branch but deliberately did not open the pull request — see \"What runs\n where\". Open it yourself:\n\n ```bash\n BRANCH=$(git ls-remote --heads \"${REMOTE}\" 'release/changelog-*' \\\n | sed 's#.*refs/heads/##')\n gh pr create --repo a2ui-project/a2ui --base main --head \"$BRANCH\" \\\n --title \"chore(release): changelog for ${RELEASED}\" \\\n --body \"Moves the \\`## Unreleased\\` entries under the released versions.\"\n ```\n\n Check the diff touches only `CHANGELOG.md` files, then ask the maintainer to\n review it. Do not leave it open: Step 3 blocks the next release until the\n branch is gone.\n\n3. **Report** the published versions, the GitHub release links, and the\n changelog pull request link.\n\n---\n\n## Troubleshooting\n\n**`could not find any workflows named release-pypi.yml`** — the workflow is only\ndispatchable once it is on `main`. Check it has merged.\n\n**HTTP 403 from Artifact Registry** — the Exit Gate allowlists\n`a2ui-project/a2ui` only. This is the expected result on a fork, and not a bug.\nOn the real repository it means the builder identity no longer matches; see\n`go/oss-exit-gate-builders`.\n\n**`Permission denied` or a failed OIDC exchange** — the Exit Gate matches the\nworkflow path and branch exactly:\n\n```\ngithub_workflow:a2ui-project/a2ui/.github/workflows/release-pypi.yml@refs/heads/main\n```\n\nRenaming or moving the workflow file breaks releases until the internal config\nis updated. It also cannot be triggered from a branch or a tag, only `main`.\n\n**`... is already on PyPI`** — the version was published previously. It cannot be\nrepublished. Work out why the tag series and PyPI disagree before retrying.\n\n**`One or more packages are not in the project's allowlist` or `400 Non-user identities cannot create new projects` in Exit Gate logs**: a brand-new package name must be added to the OSS Exit Gate allowlist and registered as a Pending Publisher on `https://pypi.org/manage/account/publishing/` before its first release. Because PyPI allows only one Pending Publisher at a time for `a2ui-py@oss-exit-gate-prod.iam.gserviceaccount.com`, publish brand-new packages one at a time. See [docs/contributing/release.md](../../../docs/contributing/release.md#releasing-a-new-package-for-the-first-time) and `go/a2ui-release#pypi`.\n\n**A dry run or failed staging left artifacts behind** — the cleanup step runs\neven on partial failure, but if it was itself skipped, remove the staged version\nby hand:\n\n```bash\ngcloud artifacts versions delete \"${VERSION}\" --package=\"${PYPI_NAME}\" \\\n --repository=a2ui--pypi --location=us --project=oss-exit-gate-prod --quiet\n```\n\n---\n\n## Rules\n\n- Never edit a version by hand. Versions come from git tags via `hatch-vcs`, and\n the workflow verifies the built artifacts against the version it planned.\n- Never push tags or run the release scripts locally to publish. The scripts\n under `.github/scripts/` are safe to run read-only for `notes`, `next`,\n `current`, `tag`, and `check`. Everything else belongs to the workflow.\n- Never dispatch `dry_run: false` without the Step 5 confirmation.\n- If the maintainer asks to skip the dry run, push back once: it is the only\n rehearsal before an irreversible publish. Defer if they insist.\n",".agents/skills/a2ui-test-quality-check/SKILL.md":"---\nname: a2ui-test-quality-check\ndescription: Auditing test suites for assertion utility, boundary cases coverage, and verification strength.\n---\n\n# A2UI Test Quality & Assertions Auditing Skill\n\nThis skill guides you through the process of auditing codebase test suites to verify that tests are providing robust, meaningful assertions and verifying critical invariants, rather than simply running paths for code coverage.\n\n---\n\n## **Instructions**\n\n1. **Locate Test Suites**:\n - Find all test directories and test files in each platform's implementation folder (e.g. `tests/`, `test/`, `*Tests.swift`).\n\n2. **Audit Assertion Quality**:\n - For each test case, inspect the assertions used:\n - Flag \"weak assertions\" that only verify non-null or truthy values without checking specific payload structure, field values, or types (e.g. `expect(result).not.toBeNull()` on a complex object).\n - Flag \"empty tests\" that execute code blocks but lack any assertions or mocks verifications (e.g. executing to check for lack of exceptions, unless it is explicitly marked as a no-throw smoke test).\n - Ensure that return models, state side effects, and events dispatched have corresponding value-matching assertions.\n\n3. **Audit Behavioral and Boundary Coverage**:\n - Review if tests exist for typical logical edge cases:\n - Null, empty, or overflow values.\n - Invalid JSON or parsing errors (e.g., throwing correct exceptions).\n - Exception propagation and error boundaries.\n - Timeout handling and cleanup side effects.\n - Look for cases where tests might pass when they should fail.\n - Cross-reference with the codebase's main files: if a file has complex parsing/validation code, ensure there are dedicated failing test cases asserting that errors are reported correctly.\n\n4. **Audit Mocking Realism**:\n - Ensure mocks and stubs verify their call parameters (e.g., verifying that a mock transport received the exact payload sent by the SDK, rather than just asserting it was called).\n\n5. **Format the Report**:\n - Build a Markdown report summarizing the findings:\n - Table of audited test suites and files.\n - **Weak Assertions**: List of test cases that rely on weak or missing assertions.\n - **Missing Edge Case Tests**: Critical logic boundaries and exception paths lacking tests.\n - **Mocking Mismatches**: Mock implementations that fail to verify call structures.\n - Return this Markdown report as your final response.\n",".agents/skills/a2ui-remediate-problem/SKILL.md":"---\nname: a2ui-remediate-problem\ndescription: Remediates a specific recommendation from an A2UI compliance report issue, or resolves any general GitHub issue, by inspecting context, implementing minimal targeted fixes, verifying tests, creating a branch, and opening a developer-signed Pull Request. Use when asked to fix or remediate an A2UI compliance audit finding, recommendation, or repository issue.\n---\n\n# A2UI Issue & Compliance Remediation Skill\n\nThis skill guides an AI coding agent or engineer on how to remediate a specific recommendation from an A2UI compliance report or resolve any general repository issue and submit a clean, developer-signed Pull Request.\n\n---\n\n## **Workflow**\n\nFollow these steps to remediate an issue:\n\n### Step 1: Identify & Read Issue Context\n\n1. **Determine the Target Issue**:\n - If the user provided an issue number or URL in their request, extract `ISSUE_NUMBER`.\n - If no issue was specified, ask the user (prefer using the `ask_question` tool):\n _\"Which GitHub issue would you like to remediate? (Please provide the issue number or URL, e.g. 2391)\"_\n\n2. **Retrieve Context & Determine Issue Type**:\n - Run the helper script to inspect the issue:\n ```bash\n python3 .agents/skills/a2ui-remediate-problem/scripts/extract_recommendation.py \"${ISSUE_NUMBER}\" [RECOMMENDATION_INDEX] --json\n ```\n - **Scenario A: Compliance Report with Multiple Recommendations**:\n - If a recommendation index was provided (e.g. `2`), the script extracts that item's details and priority.\n - If no recommendation index was specified, the script outputs all available recommendations in the issue. Ask the user (via `ask_question`) which recommendation item they would like to address.\n - Review the surrounding audit sections in the report (such as `## Codebase Blueprint Compliance Audit`, `## Code & Documentation Sync Audit`, or `## Test Quality & Assertions Audit`) for detailed findings.\n - **Scenario B: General Issue (Bug Report, Feature Request, or Non-Audit Issue)**:\n - If the issue is not a compliance report, the script returns the issue title and body as the problem statement to remediate.\n\n---\n\n### Step 2: Formulate & Apply Remediation\n\n1. Identify the files and codebases referenced by the issue or recommendation.\n2. Carefully inspect the current source code, documentation, or blueprint files.\n3. Implement the minimal necessary change to remediate the reported problem.\n - **CRITICAL RULE**: Do not make unrelated changes, refactorings, or formatting edits outside the scope of the target issue or recommendation.\n4. Format modified files and ensure code style compliance:\n ```bash\n ./scripts/fix_format.sh\n ```\n5. If modifying tests or scripts, execute local tests across the affected packages to ensure no regressions were introduced.\n\n---\n\n### Step 3: Choose Destination & Create Workspace / Branch\n\n1. Check with the user on where they would like the changes created and what branch name to use (prefer using the `ask_question` tool or equivalent interactive tool if available):\n - **Recommended branch name**: `remediation/issue-${ISSUE_NUMBER}-${RECOMMENDATION_INDEX}` (or `remediation/issue-${ISSUE_NUMBER}` for general issues).\n - Let the user choose whether to create a separate git worktree (using their preferred local worktree conventions), checkout a new branch in the current directory, or apply changes in place.\n2. Note the chosen branch name in `BRANCH_NAME`.\n3. Ensure the working tree is clean and up to date with `upstream/main`.\n\n---\n\n### Step 4: Commit Changes\n\n1. Stage all modified files relevant to the remediation:\n ```bash\n git add -u\n ```\n2. Create a conventional commit referencing the issue number:\n - For compliance recommendations:\n ```bash\n git commit -m \"fix(compliance): remediate issue #${ISSUE_NUMBER} recommendation ${RECOMMENDATION_INDEX}\"\n ```\n - For general issues:\n ```bash\n git commit -m \"fix(scope): remediate issue #${ISSUE_NUMBER} - ${CONCISE_SUMMARY}\"\n ```\n\n---\n\n### Step 5: Create Pull Request & Notify Issue (Optional / Upon Request)\n\n1. Check with the user whether they would like to submit a Pull Request (prefer using the `ask_question` tool or equivalent interactive tool if available):\n - **Recommended default**: Submit as a Draft PR (`--draft`) so CI checks run while allowing final review before requesting maintainer approvals.\n - Alternatively, submit directly as ready for review, or skip PR creation if the user wants to inspect changes locally first.\n2. If submitting a PR, generate a clear, descriptive PR title following Conventional Commits that concisely explains the specific fix being made (e.g. `fix(swift): create missing top-level README in swift/core`). **Do NOT include generic issue or recommendation numbers in the PR title.**\n3. Draft the PR description into a temporary file `pr_description.md` following [pr-description-template.md](references/pr-description-template.md).\n4. Push the branch to `origin` (or user's fork) and create the Pull Request against `main`:\n ```bash\n git push -u origin \"${BRANCH_NAME}\"\n PR_URL=$(gh pr create --draft \\\n --repo a2ui-project/a2ui \\\n --head \"${BRANCH_NAME}\" \\\n --base main \\\n --title \"${PR_TITLE}\" \\\n --body-file pr_description.md)\n ```\n _(Note: Omit `--draft` if the user prefers an immediate ready-for-review PR. If pushing from a fork, `gh pr create` automatically resolves the fork's head branch or accepts `--head :${BRANCH_NAME}`.)_\n5. Clean up the temporary file `pr_description.md`.\n6. Comment on the original issue to notify maintainers of the new PR:\n ```bash\n gh issue comment \"${ISSUE_NUMBER}\" \\\n --repo a2ui-project/a2ui \\\n --body \"🤖 Automated remediation triggered! Created PR (${PR_URL}) on branch \\`${BRANCH_NAME}\\` to address recommendation ${RECOMMENDATION_INDEX}.\"\n ```\n\n---\n\n## **References**\n\n- Refer to the [PR description template](references/pr-description-template.md) for PR body structure and guidelines.\n- Refer to the [`gh-reference`](../a2ui-audit/references/gh-reference.md) for GitHub CLI commands.\n",".agents/skills/natural-writing/SKILL.md":"---\nname: natural-writing\ndescription: Contains well-defined rules for creating natural, accurate, and readable writing. Use this skill whenever authoring longer text, including reports, PR descriptions, READMEs, system designs, analysis documents, or general documentation.\n---\n\n# Rules for natural writing\n\nThis document outlines strict rules to avoid common \"AI-isms\": stylistic and structural patterns that language models typically fall into. Follow these rules to produce content that is more understandable, and reads as natural, human-authored text.\n\nThe rules are numbered so that reviews can cite them, as in \"rule 3.2\".\n\n## 1. Vocabulary & phrasing controls\n\n### 1.1. The \"banned\" list\n\nAvoid words that are statistically overrepresented in AI text. Use simpler, more direct alternatives.\n\nAvoid verbs that are commonly overused, such as delve, underscore, highlight (as a verb), foster, cultivate, maximize, leverage, democratize, ensure, align with, resonate with, encompass, and bridge. Also avoid adverbs like seamlessly and extensively.\n\nFor nouns, avoid abstract uses of tapestry, landscape, realm, testament, interplay, synergy, cornerstone, hub, and ecosystem.\n\nFor adjectives, avoid puffery and vague descriptors like pivotal, crucial, vibrant, intricate, nuanced, unwavering, indelible, uncharted, rapidly evolving, transformative, breathtaking, nestled, dynamic, comprehensive, intuitive, holistic, robust, frictionless, scalable, and synergistic.\n\n### 1.2. Avoid \"copula\" substitutions\n\nDo not replace simple \"is\" or \"are\" verbs with flowery equivalents.\n\n- Instead of: \"The library _serves as_ a center for learning.\"\n- Write: \"The library _is_ a center for learning.\"\n- Instead of: \"The statue _stands as_ a monument to...\"\n- Write: \"The statue _is_ a monument to...\"\n\n### 1.3. Eliminate \"elegant variation\"\n\nDo not use synonyms just to avoid repeating a subject's name (e.g., \"the eponymous character,\" \"the titular protagonist,\" \"the celebrated author\"). It is acceptable to repeat the name or use pronouns naturally.\n\n### 1.4. Prefer literal words to idioms\n\nChoose the word that states the meaning directly over an idiom whose meaning depends on context. Idioms are harder to read for non-native speakers and for anyone skimming instructions.\n\n- Instead of: \"Leave the version _alone_.\"\n- Write: \"Leave the version _untouched_.\"\n\n### 1.5. Name things in full for a reader without your context\n\nUse the full name of a term when first mentioning it. Shorthand that was clear during development—such as an informal name for a part of the codebase may be meaningless to reviewers and future readers who lack that context.\n\n- Instead of: \"The suites are read through `_plain`.\"\n- Write: \"The conformance suites (the YAML test cases under `conformance/`) are read through `_plain`.\"\n\n## 2. Content & tone\n\n### 2.1. No \"puffery\" or forced significance\n\nDo not inflate the importance of a topic with vague praise. If a subject is important, the facts should demonstrate it without help.\n\nAvoid phrases like \"serves as a testament to,\" \"marking a pivotal moment,\" \"underscoring the importance of,\" \"leaving an indelible mark,\" or \"shaping the landscape.\"\n\n- Instead of: \"The founding of the institute marked a pivotal moment in the evolution of regional statistics, representing a significant shift toward independence.\"\n- Write: \"The institute was founded in 1989 to collect regional statistics.\"\n\n### 2.2. No superficial analysis\n\nAvoid attaching \"dangling\" present-participle phrases that offer vague commentary.\n\nDelete clauses starting with \"highlighting,\" \"emphasizing,\" \"reflecting,\" \"showcasing,\" or \"demonstrating\" if they just restate the obvious or add fluff.\n\n- Instead of: \"The building uses blue glass, _reflecting the region's natural beauty and symbolizing unity._\"\n- Write: \"The building uses blue glass.\"\n\n### 2.3. Avoid promotional language\n\nMaintain a neutral tone. Avoid \"advertisement\" words like boasts, features (as a verb), offers, premier, leading, state-of-the-art, committed to, and dedicated to.\n\n- Instead of: \"Nestled in the heart of the city, the hotel boasts a vibrant atmosphere.\"\n- Write: \"The hotel is located in the city center.\"\n\n### 2.4. No \"challenges and future outlook\" formula\n\nLanguage models often end articles with a generic \"Despite challenges... remains important\" conclusion. Do not end with a summary paragraph starting with \"Despite [X], [Subject] continues to...\" or speculating on the future. End with the last fact.\n\n- Bad: \"Despite facing economic hurdles, the company continues to thrive and remains a beacon of innovation.\"\n\n### 2.5. No \"title as proper noun\" leads\n\nDo not treat a descriptive article title (like a list or broad topic) as a proper noun in the first sentence.\n\n- Instead of: \"_The List of songs about Mexico_ is a curated compilation...\"\n- Write: \"This list contains songs about Mexico...\"\n\n### 2.6. No generic \"see also\" links\n\nDo not populate \"See Also\" sections with broad, generic terms. Links must be directly relevant and specific to the subject.\n\n- Bad: Linking _Financial technology_ in an article about a specific startup.\n- Good: Linking a competitor or specific related technology.\n\n### 2.7. Attribution precision\n\nAvoid vague \"weasel words\" like \"Experts argue,\" \"Observers have noted,\" or \"Several sources indicate\" unless you cite specific people immediately. Do not claim a subject interacts with a \"broader\" history or trend unless a source explicitly says so.\n\n## 3. Sentence structure\n\n### 3.1. No negative parallelism\n\nAvoid sentences that structure a contrast unnecessarily.\n\n- Instead of: \"It is _not only_ a painting, _but also_ a representation of...\"\n- Instead of: \"It is _not_ just about X; _it is_ about Y.\"\n- Write: \"It is a painting that represents...\"\n\n### 3.2. No \"rule of three\"\n\nAvoid listing exactly three adjectives or three noun phrases to sound \"comprehensive.\"\n\n- Bad: \"The event brings together _marketers, engineers, and designers_.\" (Unless those specific three groups are the _only_ ones).\n- Bad: \"It is _bold, innovative, and unique_.\"\n\n### 3.3. No false ranges\n\nDo not use \"from X to Y\" unless X and Y are endpoints of a logical scale (like time or size).\n\n- Instead of: \"The book covers everything _from_ biology _to_ space travel.\" (These are just two random topics, not a range).\n- Write: \"The book covers topics including biology and space travel.\"\n\n## 4. Structure & formatting\n\n### 4.1. Headers\n\nUse sentence case for headers (e.g., \"Early life,\" not \"Early Life\"). Do not use title case in headers.\n\n### 4.2. Formatting avoidance\n\nDo not use inline-header lists (such as `* **Header:** Description...`). Instead, use prose or simple lists.\n\nAvoid excessive bolding of keywords, \"key takeaways,\" or names in the body text, except for the first mention in the lead.\n\nUse numbered lists (`1.`, `2.`) instead of bullets, so readers can refer to an item by its number, as in \"see point 3\" (except in changelogs, which use `-` bullets; see [`update-changelog`](../update-changelog/SKILL.md)). Do not use emojis (🚀, 🧠) as list markers.\n\nAvoid creating tables for simple information that easily fits in a sentence.\n\nEnsure markup is context-appropriate; do not use Markdown (like `##`) in formats that do not support it (like Wikitext) unless it is explicitly converted.\n\n### 4.3. Punctuation\n\nUse straight quotes (`\"`, `'`) and straight apostrophes (`'`). Do not use curly or smart quotes (`“`, `’`).\n\nUse em dashes sparingly, as language models often overuse them for emphasis. Prefer commas or parentheses instead.\n\n## 5. Citations & integrity\n\n### 5.1. No hallucinations\n\nNever generate a citation unless you are looking at the source.\nDo not invent URLs or DOIs.\nDo not assume a book exists or contains a specific fact without verification.\n\n### 5.2. Link what you mention\n\nLink everything the reader may want to open: files, functions, test and conformance cases, packages, issues, pull requests, and external pages. How precise a link should be depends on how long the text lives.\n\n1. In short-lived text, such as review comments, PR descriptions, and issues, link to the exact lines. Pin the link to a commit SHA rather than a branch, so it keeps pointing at the lines you meant after the branch moves. For a Markdown file, add `?plain=1` so a line anchor such as `#L10-L20` works.\n2. In long-lived documents, such as READMEs, documentation, skills, and code comments, link to the file or its section, without line ranges. A line range in one long-lived document has to be updated every time the document it points to changes.\n3. Link only to what the reader can see at the link target. If your change is not pushed yet, link to the current version, or post the text after the push.\n4. Before posting, check that every link resolves.\n\n## 6. Communication (chat context)\n\nAvoid collaborative filler at the start of responses, such as \"Certainly!\", \"Here is the information,\" or \"I hope this helps.\" State the content directly.\n\nDo not apologize for being an AI or mention knowledge cutoffs unless it is relevant to a specific, time-sensitive fact.\n\nDo not preface responses with subject lines.\n\nKeep edit summaries concise and informal, avoiding verbose paragraphs.\n",".agents/skills/inspect-ai/SKILL.md":"---\nname: inspect-ai\ndescription: Useful when working with the Inspect AI evaluation framework (e.g., in the eval/ directory). Provides instructions on how to access Inspect AI documentation.\n---\n\n# Inspect AI Framework Guidelines\n\nWhen you are tasked with creating, modifying, or debugging evaluation scripts (especially within the `eval/` directory) that utilize the **Inspect AI** framework, you should consult the official documentation to ensure you are using the correct APIs, solvers, scorers, and best practices.\n\n### Documentation Source\n\nTo learn how to use Inspect AI, read the official LLM-optimized documentation guide by fetching the following URL using your `read_url_content` tool:\n\n`https://inspect.aisi.org.uk/llms.txt`\n\nAlways reference this document when you need clarification on how Inspect AI handles task execution, scoring objects, parallelism, or tool calling architectures.\n",".agents/skills/coding-principles/SKILL.md":"---\nname: coding-principles\ndescription: >-\n Enforces engineering, architecture, public API, and code quality standards distilled from human\n reviewer feedback across A2UI pull requests. Use when authoring new code, refactoring, addressing\n review feedback, or reviewing PR diffs. Don't use for release publishing or spec blueprint\n generation without code or PR changes.\n---\n\n# Skill: coding-principles\n\n**Purpose**: Core engineering, architecture, and code quality standards established by human reviewers across A2UI pull requests. Used by agents when authoring changes, refactoring code, addressing review feedback, or reviewing pull request diffs to maintain repository health across all languages.\n\n---\n\n## Specification and Blueprint Grounding\n\nBefore modifying or implementing code in any language, consult the authoritative specifications and blueprints:\n\n- **Protocol JSON Schemas**: [`specification/v0_9_1/json/`](../../../specification/v0_9_1/json/) and [`specification/v1_0/json/`](../../../specification/v1_0/json/) define wire-format envelopes, types, and validation constraints.\n- **Component Catalogs**: [`catalogs/basic/v1/catalog.json`](../../../catalogs/basic/v1/catalog.json) defines standard components, properties, and function signatures.\n- **Core Module Blueprint**: [`a2ui_core.blueprint.md`](../../../blueprints/modules/a2ui_core.blueprint.md) specifies state containers (`DataModel`, `SurfaceModel`), `MessageProcessor`, JSON pointer rules, auto-vivification, and error semantics.\n- **Agent SDK Blueprint**: [`a2ui_agent.blueprint.md`](../../../blueprints/modules/a2ui_agent.blueprint.md) specifies `A2uiGenerator`, `A2uiRequestProcessor`, inference format strategies, and prompt generation.\n- **Framework Adapter Blueprint**: [`a2ui_framework_adapter.blueprint.md`](../../../blueprints/modules/a2ui_framework_adapter.blueprint.md) specifies view mapping, reactive subscription lifecycles, and layout behavior.\n- **Typesafe Builder Blueprint**: [`typesafe_builder_api.blueprint.md`](../../../blueprints/features/typesafe_builder_api.blueprint.md) specifies fluent builder hierarchies.\n- **Reference Implementation**: [`typescript/core/web_core/`](../../../typescript/core/web_core/) serves as the canonical behavioral reference for edge-case resolution.\n\n---\n\n## Progressive Discoverability: Two-Level Subskill Routing\n\nBecause the A2UI repository spans multiple languages (`typescript/`, `python/`, `dart/`, `swift/`) and shared specifications (`specification/`, `catalogs/`), agents must use a two-level progressive discovery workflow:\n\n1. **Level 1 (Cross-Language Subskills)**: Activate language-agnostic principles that govern pull request scope, software design, public API boundaries, specification immutability, and changelogs across the entire monorepo.\n2. **Level 2 (Language-Specific Routing)**: Route by the programming languages modified in the diff to load only the subskills and language guides relevant to those languages.\n\n### Step 1: Inspect the PR Diff\n\nReview the modified files and categories of changes:\n\n```bash\n# In an active branch:\ngit diff main --stat\n```\n\nIdentify both:\n\n- **Cross-cutting functional areas** impacted (public exports, specifications, catalogs, changelogs, PR structure).\n- **Programming languages and directories** touched (`typescript/`, `python/`, `dart/`, `swift/`, `samples/`, `tools/`).\n\n---\n\n### Step 2: Activate Cross-Language Subskills (Language-Agnostic)\n\nEvaluate the cross-language subskills below against the diff and read any activated document in full:\n\n#### 1. PR Hygiene, Atomicity, Scope Control & Software Design\n\n- **Skill**: [`pr-hygiene`](../pr-hygiene/SKILL.md)\n- **Activate if**: Always applicable when authoring, preparing, or reviewing a pull request.\n\n#### 2. Public API Boundaries, Cross-Framework Design & Changelogs\n\n- **Document**: [`subskills/public-api-and-cross-framework-design.md`](subskills/public-api-and-cross-framework-design.md)\n- **Activate if**:\n - Any package entrypoint or facade (`index.ts`, `public-api.ts`, `package.json`, `__init__.py`, `lib/*.dart`, or public Swift API), or any `CHANGELOG.md` is modified.\n - Any new class, function, interface, type, model, or DI token is exported.\n - Renderer APIs, registration helpers, or adapters across `@a2ui/angular`, `@a2ui/lit`, `@a2ui/react`, `a2ui_flutter`, or `A2UISwiftUI` are modified.\n - Imports between sibling packages change.\n - Files under `specification/` or `catalogs/` (schemas, catalog fixtures, or examples) are modified or added.\n - Breaking changes or public API deprecations are introduced.\n - A new source file is added (verify it has a single responsibility rather than acting as a catch-all `types.*` or `utils.*` file).\n\n#### 3. Updating Changelogs (`CHANGELOG.md`)\n\n- **Skill**: [`update-changelog`](../update-changelog/SKILL.md)\n- **Activate if**: Any `CHANGELOG.md` is modified or a published package's public API or consumer-observable behavior changes.\n\n---\n\n### Step 3: Route by Language for Language-Dependent Principles\n\nInspect the file extensions and directories in `git diff main --stat` and follow the matching language route(s) below. Only load routers and guides for languages present in your diff:\n\n| Language / Ecosystem | Matching Paths & Extensions | Progressive Discovery Target |\n| :-------------------------------------------------------------- | :--------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **TypeScript & Web** (Lit, Angular, React, Web Core, CSS, HTML) | `*.ts`, `*.tsx`, `*.css`, `typescript/`, `samples/client/{lit,angular,react}/`, `tools/` | Read the TypeScript & Web router: [`subskills/typescript/INDEX.md`](subskills/typescript/INDEX.md) to activate specific TypeScript, reactive lifecycle, CSS theming, accessibility, DOM testing, and AST public API subskills. |\n| **Python** (Core, Agent SDK, Builders, Evaluators, Scripts) | `*.py`, `python/`, `eval/`, `samples/agent/`, `tools/`, `scripts/` | Read the Python router: [`subskills/python/INDEX.md`](subskills/python/INDEX.md) to activate Python package architecture, facade conventions, typing, and verification subskills. |\n| **Swift & SwiftUI** (Core, SwiftUI Adapter, iOS Sample) | `*.swift`, `swift/`, `Package.swift` | Read the Swift & SwiftUI router: [`subskills/swift/INDEX.md`](subskills/swift/INDEX.md) to activate Swift target architecture, coding standards, and `Testing` subskills. |\n| **Dart & Flutter** (Core, Agent SDK, Flutter Adapter) | `*.dart`, `dart/`, `samples/client/flutter/`, `pubspec.yaml` | Read the Dart & Flutter router: [`subskills/dart/INDEX.md`](subskills/dart/INDEX.md) to activate Dart analyzer rules, package versioning, and changelog subskills. |\n\n---\n\n### Step 4: Progressively Load Activated Subskills\n\nRead only the cross-language subskills activated in Step 2 and the language-specific subskills selected through Step 3 to evaluate your code against their rationales, checklists, and examples without loading unrelated language rules into context.\n",".agents/skills/pr-hygiene/SKILL.md":"# pr-hygiene\n\nPath: `.agents/skills/pr-hygiene/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/pr-hygiene/SKILL.md)",".agents/skills/update-changelog/SKILL.md":"# update-changelog\n\nPath: `.agents/skills/update-changelog/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/update-changelog/SKILL.md)","blueprints/skills/a2ui-blueprint-compliance/SKILL.md":"# a2ui-blueprint-compliance\n\nPath: `blueprints/skills/a2ui-blueprint-compliance/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/blueprints/skills/a2ui-blueprint-compliance/SKILL.md)","blueprints/skills/a2ui-blueprint-maintenance/SKILL.md":"# a2ui-blueprint-maintenance\n\nPath: `blueprints/skills/a2ui-blueprint-maintenance/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/blueprints/skills/a2ui-blueprint-maintenance/SKILL.md)","blueprints/skills/a2ui-blueprint-navigator/SKILL.md":"# a2ui-blueprint-navigator\n\nPath: `blueprints/skills/a2ui-blueprint-navigator/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/blueprints/skills/a2ui-blueprint-navigator/SKILL.md)","blueprints/skills/a2ui-create-feature-blueprint/SKILL.md":"# a2ui-create-feature-blueprint\n\nPath: `blueprints/skills/a2ui-create-feature-blueprint/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/blueprints/skills/a2ui-create-feature-blueprint/SKILL.md)","blueprints/skills/a2ui-implement-feature-from-blueprint/SKILL.md":"# a2ui-implement-feature-from-blueprint\n\nPath: `blueprints/skills/a2ui-implement-feature-from-blueprint/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/blueprints/skills/a2ui-implement-feature-from-blueprint/SKILL.md)","conformance/test_data/skills/express_basic_catalog.skill.md":"# Skills Skill\n\nPath: `conformance/test_data/skills/express_basic_catalog.skill.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/conformance/test_data/skills/express_basic_catalog.skill.md)","conformance/test_data/skills/express_basic_monolithic.skill.md":"# Skills Skill\n\nPath: `conformance/test_data/skills/express_basic_monolithic.skill.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/conformance/test_data/skills/express_basic_monolithic.skill.md)","conformance/test_data/skills/express_core.skill.md":"# Skills Skill\n\nPath: `conformance/test_data/skills/express_core.skill.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/conformance/test_data/skills/express_core.skill.md)","conformance/test_data/skills/fake_monolithic.skill.md":"# Skills Skill\n\nPath: `conformance/test_data/skills/fake_monolithic.skill.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/conformance/test_data/skills/fake_monolithic.skill.md)","eval/iterative_format_optimizer/skills/inference-format-optimizer/SKILL.md":"# inference-format-optimizer\n\nPath: `eval/iterative_format_optimizer/skills/inference-format-optimizer/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/iterative_format_optimizer/skills/inference-format-optimizer/SKILL.md)","AGENTS.md":"# AI Agent Protocol & Instructions\n\nPath: `AGENTS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/AGENTS.md)",".gemini/GEMINI.md":"# .gemini - Gemini Agent & Antigravity Instructions\n\nPath: `.gemini/GEMINI.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.gemini/GEMINI.md)","eval/DESIGN.md":"# eval - UI Design System & Style Tokens\n\nPath: `eval/DESIGN.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/DESIGN.md)","swift/AGENTS.md":"# swift - AI Agent Protocol & Instructions\n\nPath: `swift/AGENTS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/swift/AGENTS.md)","tools/build_catalog/README.md":"# build_catalog Documentation\n\nPath: `tools/build_catalog/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/README.md)","tools/composer/AGENTS.md":"# Composer Skill\n\nPath: `tools/composer/AGENTS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/AGENTS.md)","tools/composer/README.md":"# composer Documentation\n\nPath: `tools/composer/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/README.md)","tools/composer/components.json":"# Composer Skill\n\nPath: `tools/composer/components.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/components.json)","tools/composer/package.json":"# Composer Skill\n\nPath: `tools/composer/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/package.json)","tools/composer/tsconfig.json":"# Composer Skill\n\nPath: `tools/composer/tsconfig.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/tsconfig.json)","tools/editor/README.md":"# editor Documentation\n\nPath: `tools/editor/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/editor/README.md)","tools/editor/package.json":"# Editor Skill\n\nPath: `tools/editor/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/editor/package.json)","tools/editor/tsconfig.json":"# Editor Skill\n\nPath: `tools/editor/tsconfig.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/editor/tsconfig.json)","tools/inspector/README.md":"# inspector Documentation\n\nPath: `tools/inspector/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/inspector/README.md)","tools/inspector/package.json":"# Inspector Skill\n\nPath: `tools/inspector/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/inspector/package.json)","tools/inspector/tsconfig.json":"# Inspector Skill\n\nPath: `tools/inspector/tsconfig.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/inspector/tsconfig.json)",".agents/skills/a2ui-issue-triage/README.md":"# A2ui-issue-triage Skill\n\nPath: `.agents/skills/a2ui-issue-triage/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/a2ui-issue-triage/README.md)","conformance/extensions/a2a/a2a_integration.yaml":"# A2a Skill\n\nPath: `conformance/extensions/a2a/a2a_integration.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/conformance/extensions/a2a/a2a_integration.yaml)","conformance/extensions/adk/adk_extensions.yaml":"# Adk Skill\n\nPath: `conformance/extensions/adk/adk_extensions.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/conformance/extensions/adk/adk_extensions.yaml)","typescript/agents/a2ui_agent/CHANGELOG.md":"# Subagent: changelog\n\nPath: `typescript/agents/a2ui_agent/CHANGELOG.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/typescript/agents/a2ui_agent/CHANGELOG.md)","typescript/agents/a2ui_agent/KNOWN_GAPS.md":"# Subagent: known_gaps\n\nPath: `typescript/agents/a2ui_agent/KNOWN_GAPS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/typescript/agents/a2ui_agent/KNOWN_GAPS.md)","typescript/agents/a2ui_agent/README.md":"# Subagent: readme\n\nPath: `typescript/agents/a2ui_agent/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/typescript/agents/a2ui_agent/README.md)","typescript/agents/a2ui_agent/package.json":"# A2ui_agent Skill\n\nPath: `typescript/agents/a2ui_agent/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/typescript/agents/a2ui_agent/package.json)","typescript/agents/a2ui_agent/tsconfig.check.json":"# A2ui_agent Skill\n\nPath: `typescript/agents/a2ui_agent/tsconfig.check.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/typescript/agents/a2ui_agent/tsconfig.check.json)","typescript/agents/a2ui_agent/tsconfig.json":"# A2ui_agent Skill\n\nPath: `typescript/agents/a2ui_agent/tsconfig.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/typescript/agents/a2ui_agent/tsconfig.json)",".agents/skills/a2ui-audit/references/gh-reference.md":"# References Skill\n\nPath: `.agents/skills/a2ui-audit/references/gh-reference.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/a2ui-audit/references/gh-reference.md)",".agents/skills/a2ui-issue-triage/references/triage_criteria.md":"# References Skill\n\nPath: `.agents/skills/a2ui-issue-triage/references/triage_criteria.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/a2ui-issue-triage/references/triage_criteria.md)",".agents/skills/a2ui-remediate-problem/references/pr-description-template.md":"# References Skill\n\nPath: `.agents/skills/a2ui-remediate-problem/references/pr-description-template.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/a2ui-remediate-problem/references/pr-description-template.md)",".agents/skills/coding-principles/subskills/public-api-and-cross-framework-design.md":"# Subskills Skill\n\nPath: `.agents/skills/coding-principles/subskills/public-api-and-cross-framework-design.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/public-api-and-cross-framework-design.md)","tools/build_catalog/tests/fixtures/basic_catalog.json":"# Fixtures Skill\n\nPath: `tools/build_catalog/tests/fixtures/basic_catalog.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/tests/fixtures/basic_catalog.json)","tools/build_catalog/tests/fixtures/common_types.json":"# Fixtures Skill\n\nPath: `tools/build_catalog/tests/fixtures/common_types.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/tests/fixtures/common_types.json)","tools/build_catalog/tests/fixtures/component1.json":"# Fixtures Skill\n\nPath: `tools/build_catalog/tests/fixtures/component1.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/tests/fixtures/component1.json)","tools/build_catalog/tests/fixtures/component2.json":"# Fixtures Skill\n\nPath: `tools/build_catalog/tests/fixtures/component2.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/tests/fixtures/component2.json)","tools/build_catalog/tests/fixtures/component3.json":"# Fixtures Skill\n\nPath: `tools/build_catalog/tests/fixtures/component3.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/tests/fixtures/component3.json)","tools/build_catalog/tests/fixtures/v0_8_custom_catalog.json":"# Fixtures Skill\n\nPath: `tools/build_catalog/tests/fixtures/v0_8_custom_catalog.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/tests/fixtures/v0_8_custom_catalog.json)","tools/build_catalog/tests/fixtures/v0_8_standard_catalog_definition.json":"# Fixtures Skill\n\nPath: `tools/build_catalog/tests/fixtures/v0_8_standard_catalog_definition.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/tests/fixtures/v0_8_standard_catalog_definition.json)",".agents/skills/coding-principles/subskills/dart/INDEX.md":"# Dart Skill\n\nPath: `.agents/skills/coding-principles/subskills/dart/INDEX.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/dart/INDEX.md)",".agents/skills/coding-principles/subskills/dart/versioning-and-releases.md":"# Dart Skill\n\nPath: `.agents/skills/coding-principles/subskills/dart/versioning-and-releases.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/dart/versioning-and-releases.md)",".agents/skills/coding-principles/subskills/python/INDEX.md":"# Python Skill\n\nPath: `.agents/skills/coding-principles/subskills/python/INDEX.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/python/INDEX.md)",".agents/skills/coding-principles/subskills/python/architecture-and-facades.md":"# Python Skill\n\nPath: `.agents/skills/coding-principles/subskills/python/architecture-and-facades.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/python/architecture-and-facades.md)",".agents/skills/coding-principles/subskills/python/coding-standards-and-verification.md":"# Python Skill\n\nPath: `.agents/skills/coding-principles/subskills/python/coding-standards-and-verification.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/python/coding-standards-and-verification.md)",".agents/skills/coding-principles/subskills/swift/INDEX.md":"# Swift Skill\n\nPath: `.agents/skills/coding-principles/subskills/swift/INDEX.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/swift/INDEX.md)",".agents/skills/coding-principles/subskills/swift/coding-standards-and-testing.md":"# Swift Skill\n\nPath: `.agents/skills/coding-principles/subskills/swift/coding-standards-and-testing.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/swift/coding-standards-and-testing.md)",".agents/skills/coding-principles/subskills/typescript/INDEX.md":"# Typescript Skill\n\nPath: `.agents/skills/coding-principles/subskills/typescript/INDEX.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/INDEX.md)",".agents/skills/coding-principles/subskills/typescript/accessibility-semantics.md":"# Typescript Skill\n\nPath: `.agents/skills/coding-principles/subskills/typescript/accessibility-semantics.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/accessibility-semantics.md)",".agents/skills/coding-principles/subskills/typescript/css-theming-styling.md":"# Typescript Skill\n\nPath: `.agents/skills/coding-principles/subskills/typescript/css-theming-styling.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/css-theming-styling.md)",".agents/skills/coding-principles/subskills/typescript/reactive-lifecycle-performance.md":"# Typescript Skill\n\nPath: `.agents/skills/coding-principles/subskills/typescript/reactive-lifecycle-performance.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/reactive-lifecycle-performance.md)",".agents/skills/coding-principles/subskills/typescript/testing-isolation.md":"# Typescript Skill\n\nPath: `.agents/skills/coding-principles/subskills/typescript/testing-isolation.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/testing-isolation.md)",".agents/skills/coding-principles/subskills/typescript/typescript-closure-compiler.md":"# Typescript Skill\n\nPath: `.agents/skills/coding-principles/subskills/typescript/typescript-closure-compiler.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/typescript-closure-compiler.md)","blueprints/codebases/typescript/agents/a2ui_agent/codebase.blueprint.md":"# Subagent: codebase.blueprint\n\nPath: `blueprints/codebases/typescript/agents/a2ui_agent/codebase.blueprint.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/blueprints/codebases/typescript/agents/a2ui_agent/codebase.blueprint.md)","eval/iterative_format_optimizer/skills/inference-format-optimizer/references/agent_instructions.md":"# References Skill\n\nPath: `eval/iterative_format_optimizer/skills/inference-format-optimizer/references/agent_instructions.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/iterative_format_optimizer/skills/inference-format-optimizer/references/agent_instructions.md)","eval/iterative_format_optimizer/skills/inference-format-optimizer/references/inference_format_iteration.md":"# References Skill\n\nPath: `eval/iterative_format_optimizer/skills/inference-format-optimizer/references/inference_format_iteration.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/iterative_format_optimizer/skills/inference-format-optimizer/references/inference_format_iteration.md)","eval/iterative_format_optimizer/skills/inference-format-optimizer/references/scoring_model.md":"# References Skill\n\nPath: `eval/iterative_format_optimizer/skills/inference-format-optimizer/references/scoring_model.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/iterative_format_optimizer/skills/inference-format-optimizer/references/scoring_model.md)","eval/iterative_format_optimizer/skills/inference-format-optimizer/references/subagent_protocol.md":"# References Skill\n\nPath: `eval/iterative_format_optimizer/skills/inference-format-optimizer/references/subagent_protocol.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/iterative_format_optimizer/skills/inference-format-optimizer/references/subagent_protocol.md)","eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/README.md":"# Scripts Skill\n\nPath: `eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/README.md)","eval/iterative_format_optimizer/skills/inference-format-optimizer/templates/subagent_prompt.md":"# Templates Skill\n\nPath: `eval/iterative_format_optimizer/skills/inference-format-optimizer/templates/subagent_prompt.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/iterative_format_optimizer/skills/inference-format-optimizer/templates/subagent_prompt.md)","specification/v1_0/extensions/a2a/docs/a2ui_extension_specification.md":"# Docs Skill\n\nPath: `specification/v1_0/extensions/a2a/docs/a2ui_extension_specification.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/specification/v1_0/extensions/a2a/docs/a2ui_extension_specification.md)","tools/composer/src/data/theater/booking-form.json":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/booking-form.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/booking-form.json)","tools/composer/src/data/theater/component-gallery-stream.json":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/component-gallery-stream.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/component-gallery-stream.json)","tools/composer/src/data/theater/contact-card.json":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/contact-card.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/contact-card.json)","tools/composer/src/data/theater/flight-status.json":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/flight-status.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/flight-status.json)","tools/composer/src/data/theater/floor-plan.json":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/floor-plan.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/floor-plan.json)","tools/composer/src/data/theater/kitchen-sink.json":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/kitchen-sink.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/kitchen-sink.json)","tools/composer/src/data/theater/northstar-tour.json":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/northstar-tour.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/northstar-tour.json)","tools/composer/src/data/theater/org-chart.json":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/org-chart.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/org-chart.json)","tools/composer/src/data/theater/restaurant-booking.json":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/restaurant-booking.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/restaurant-booking.json)","tools/composer/src/data/theater/restaurant-confirmation.json":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/restaurant-confirmation.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/restaurant-confirmation.json)","tools/composer/src/data/theater/restaurant-finder.json":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/restaurant-finder.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/restaurant-finder.json)","tools/composer/src/data/theater/restaurant-grid.json":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/restaurant-grid.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/restaurant-grid.json)","tools/composer/src/data/theater/rizzcharts-chart.json":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/rizzcharts-chart.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/rizzcharts-chart.json)","tools/composer/src/data/theater/weather-widget.json":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/weather-widget.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/weather-widget.json)",".agents/skills/coding-principles/subskills/typescript/references/inspecting-typescript-public-api.md":"# References Skill\n\nPath: `.agents/skills/coding-principles/subskills/typescript/references/inspecting-typescript-public-api.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/references/inspecting-typescript-public-api.md)"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# AI Agent Protocol & Instructions\n\nPath: `AGENTS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/AGENTS.md)","tokens":300,"sizeBytes":151},{"name":"AGENTS.md","path":"swift/AGENTS.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/swift/AGENTS.md","title":"swift - AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# swift - AI Agent Protocol & Instructions\n\nPath: `swift/AGENTS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/swift/AGENTS.md)","tokens":300,"sizeBytes":171},{"name":"DESIGN.md","path":"eval/DESIGN.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/DESIGN.md","title":"eval - UI Design System & Style Tokens","category":"project-spec","format":"markdown","content":"# eval - UI Design System & Style Tokens\n\nPath: `eval/DESIGN.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/DESIGN.md)","tokens":300,"sizeBytes":167},{"name":"SKILL.md","path":".agents/skills/a2ui-add-eval-datapoint/SKILL.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/a2ui-add-eval-datapoint/SKILL.md","title":"a2ui-add-eval-datapoint","category":"anthropic-skill","format":"markdown","content":"---\nname: a2ui-add-eval-datapoint\ndescription: Step-by-step workflow for adding and verifying new evaluation data points in the A2UI evaluation suite.\n---\n\n# Adding and verifying A2UI evaluation data points\n\nUse this skill when adding new data points or datasets to the A2UI evaluation framework in `eval/`.\n\n## References\n\nFor full architecture and setup details, consult:\n\n- `eval/CONTRIBUTING_USE_CASES.md`: The authoritative contributor guide for evaluation use cases, containing field definitions, context rules, and unencrypted multi-turn examples.\n- `eval/README.md`: Evaluation quickstart, Transcrypt setup, and CLI flags.\n- `eval/DESIGN.md`: Architecture, multi-stage scorers, and encryption-at-rest design.\n- `eval/datasets/dataset_schema.json`: Formal JSON Schema defining required fields and structural rules for evaluation data points.\n\n---\n\n## Step-by-step workflow\n\n### 1. Unlock Transcrypt\n\nDatasets in `eval/datasets/` are encrypted at rest. Unlock Transcrypt locally before authoring (ask an A2UI team member for the password):\n\n```bash\ncd eval\nbin/transcrypt -y -c aes-256-cbc -p \n```\n\n### 2. Author the data point\n\nCreate or update a dataset file in `eval/datasets/.yaml` (e.g. `eval/datasets/my_dataset.yaml`).\n\nEvery data point **must conform** to the JSON Schema in `eval/datasets/dataset_schema.json` and follow the authoring guidelines in `eval/CONTRIBUTING_USE_CASES.md`.\n\nFor a complete unencrypted reference example of a multi-turn conversation with system instructions, tool calls (including unrelated background tool calls), tool responses, and a judging target rubric, inspect `eval/examples/example_eval_case.json`.\n\n**Key authoring requirements from `eval/CONTRIBUTING_USE_CASES.md`:**\n\n- Include the full multi-turn conversation history (`messages`), including assistant function calls (`tool_calls`) and tool responses (`role: tool`). Do not use single-turn prompts.\n- Write the `target` as a qualitative judging rubric for the LLM-as-a-judge (what UI components must appear, data binding rules, and what errors to penalize). Do not include a hardcoded JSON string, as that ties the evaluation to a particular inference format.\n\n### 3. Validate schema compliance\n\nVerify that all data points satisfy `eval/datasets/dataset_schema.json`:\n\n```bash\ncd eval\nuv run python -m pytest tests/test_dataset.py\n```\n\n### 4. Run an evaluation on the new data point\n\nAlways execute an evaluation run on the newly added dataset to verify model inference and scoring:\n\n```bash\ncd eval\n# Quick validation on gemini-3.1-flash-lite\nuv run main.py --dataset my_dataset --sanity\n\n# Full evaluation check\nuv run main.py --dataset my_dataset\n```\n\nView the interactive traces and judging rationales:\n\n```bash\nuv run inspect view start\n```\n\n### 5. Verify encryption and commit\n\nWhen staging changes, Git applies the Transcrypt clean filter. Confirm that the staged file is encrypted ciphertext before committing:\n\n```bash\n# Stage the new dataset file\ngit add eval/datasets/my_dataset.yaml\n\n# Verify staged content is encrypted ciphertext (not plaintext)\ngit diff --cached eval/datasets/my_dataset.yaml\n\n# Commit the encrypted data point\ngit commit -m \"feat(eval): add my_dataset evaluation data points\"\n```\n","frontmatter":{"name":"a2ui-add-eval-datapoint","description":"Step-by-step workflow for adding and verifying new evaluation data points in the A2UI evaluation suite."},"isInternal":false,"tokens":725,"sizeBytes":3241},{"name":"gh-reference.md","path":".agents/skills/a2ui-audit/references/gh-reference.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/a2ui-audit/references/gh-reference.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# References Skill\n\nPath: `.agents/skills/a2ui-audit/references/gh-reference.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/a2ui-audit/references/gh-reference.md)","tokens":300,"sizeBytes":221},{"name":"SKILL.md","path":".agents/skills/a2ui-audit/SKILL.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/a2ui-audit/SKILL.md","title":"a2ui-audit","category":"anthropic-skill","format":"markdown","content":"---\nname: a2ui-audit\ndescription: Main coordination skill to run the blueprint compliance, documentation synchronization, and test quality audits, posting the combined results as a labeled GitHub issue.\n---\n\n# A2UI Compliance Verification Skill\n\nThis skill coordinates the execution of specification compliance, documentation\nsync, and test quality audits, and publishes the combined results as a GitHub issue.\n\nOther than writing a report and creating an issue, this skill is purely a\nread-only skill; no changes are to be made to the codebase. Do not attempt to\nfix issues.\n\n---\n\n## **Instructions**\n\n1. **Audit Codebase Blueprint Compliance**:\n - Execute `python3 blueprints/skills/a2ui-blueprint-compliance/scripts/check_compliance.py` to dynamically discover all 8 production codebases and generate the baseline Markdown status report.\n - Run the sub-skill [`a2ui-blueprint-compliance`](../../../blueprints/skills/a2ui-blueprint-compliance/SKILL.md) to audit each discovered codebase for missing features or blueprint drift.\n - Save the compiled Markdown report to a temporary file in the workspace (e.g., `compliance_report.md`) under the header `## Codebase Blueprint Compliance Audit`.\n\n2. **Audit Code vs. Documentation Synchronization**:\n - Run the sub-skill [`a2ui-doc-sync-check`](../a2ui-doc-sync-check/SKILL.md) to audit documentation drift across `docs/`, `specification/`, codebase READMEs, and inline docstrings.\n - Append the returned Markdown report to `compliance_report.md` under a new header `## Code & Documentation Sync Audit`.\n\n3. **Audit Test Quality & Assertion Strength**:\n - Run the sub-skill [`a2ui-test-quality-check`](../a2ui-test-quality-check/SKILL.md) to audit test suites across all codebases for weak assertions and behavioral verification.\n - Append the returned Markdown report to `compliance_report.md` under a new header `## Test Quality & Assertions Audit`.\n\n4. **Summarize the report**:\n - Add a `## Summary` section at the top of the `compliance_report.md` file with a detailed overview of the audit scope and key findings across all audited codebases.\n - Add a `## Recommendations` section listing actionable, prioritized follow-up items formatted as a numbered list (e.g. `1. **P0**: ...`). Each numbered item MUST represent a concrete, self-contained remediation task.\n - Immediately below the recommendations list, include the mandatory automated remediation callout:\n > 🤖 **Automated Remediation**: Comment `/fix ` (e.g., `/fix 1`) on this issue to have an agent create a draft PR for that recommendation.\n\n5. **Format and Detail Requirements**:\n - **MANDATORY COMPLETE REPOSITORY COVERAGE**: The report MUST include status rows and detailed findings for **ALL 8 production codebases** discovered by `check_compliance.py`. Do NOT truncate, shortcut, or abbreviate the summary tables or detailed findings.\n - For each audit section, provide specific evidence:\n - Exact file paths (e.g. `python/a2ui_agent/transport.py:L45-L60`).\n - Specific function/class names, parameter mismatches, or missing feature descriptions.\n - Concrete examples of weak assertions (e.g. `assert response is not None` in `eval/tests/test_strategies.py`).\n - Follow the structure provided in the **Report Format Template** below.\n\n6. **Publish Report**:\n - Execute the local Python helper script to create the GitHub issue containing the combined reports:\n ```bash\n python3 .agents/skills/a2ui-audit/scripts/create_compliance_report.py compliance_report.md --repo a2ui-project/a2ui\n ```\n - The publishing script will create the GitHub issue, automatically inject copyable remediation prompt blocks referencing the newly created issue URL under each recommendation item, and update the issue body.\n - Ensure the helper script runs successfully.\n - Clean up the temporary file `compliance_report.md` after completion.\n\n---\n\n## **Report Format Template**\n\nWhen compiling `compliance_report.md`, use the following structure:\n\n```markdown\n## Summary\n\n[Provide a 2-3 paragraph detailed summary explaining the repository state, key areas audited across SDKs, renderers, and tests, and major findings.]\n\n## Recommendations\n\n1. **[Priority]**: **[Title]**\n - [Clear detailed explanation of the fix needed, specifying affected directories or modules.]\n\n2. **[Priority]**: **[Title]**\n - [Clear detailed explanation of the fix needed, specifying affected directories or modules.]\n\n## Codebase Blueprint Compliance Audit\n\n| Codebase Implementation | Associated Module | Status | Commits Behind | Current Commit | Latest Commit |\n| ----------------------- | ------------------- | ------ | -------------- | -------------- | ------------- |\n| `path/to/codebase` | `associated_module` | Status | X | `commit_hash` | `latest_hash` |\n\n### Detailed Findings & Discrepancies\n\n- **[Codebase Path]**: [Detailed description of missing specifications, missing required features, or frontmatter commit hash drift.]\n\n## Code & Documentation Sync Audit\n\n| Directory | Status | Identified Issues |\n| ------------- | ------ | ----------------- |\n| `path/to/dir` | Status | Brief Summary |\n\n### Detailed Findings\n\n- **README Mismatches**:\n - `path/to/README.md`: [Exact invalid command or outdated setup step found in README.]\n- **Docstring / API Drift**:\n - `path/to/file.ext:L12-L34`: [Specific parameter or return type mismatch between implementation and docstring/comments.]\n\n## Test Quality & Assertions Audit\n\n| Suite / Module | Status | Observations |\n| --------------- | ------ | ------------- |\n| `path/to/tests` | Status | Brief Summary |\n\n### Detailed Findings\n\n- **Weak Assertions**:\n - `path/to/test_file.ext` (`test_function_name`): [Explanation of weak assertion, e.g. using `assertNotNull` instead of schema/type check.]\n- **Missing Edge Case Tests**:\n - `path/to/module`: [Boundary conditions, error cases, or invalid inputs that lack test coverage.]\n```\n\n---\n\n## **References**\n\n- Refer to the [`a2ui-blueprint-compliance`](../../../blueprints/skills/a2ui-blueprint-compliance/SKILL.md) skill for codebase blueprint checking.\n- Refer to the [`a2ui-doc-sync-check`](../a2ui-doc-sync-check/SKILL.md) skill for documentation sync checking.\n- Refer to the [`a2ui-test-quality-check`](../a2ui-test-quality-check/SKILL.md) skill for test quality and assertion checking.\n- Refer to the [`gh-reference`](./references/gh-reference.md) reference for GitHub CLI (`gh`) operations.\n","frontmatter":{"name":"a2ui-audit","description":"Main coordination skill to run the blueprint compliance, documentation synchronization, and test quality audits, posting the combined results as a labeled GitHub issue."},"isInternal":false,"tokens":1439,"sizeBytes":6493},{"name":"SKILL.md","path":".agents/skills/a2ui-doc-sync-check/SKILL.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/a2ui-doc-sync-check/SKILL.md","title":"a2ui-doc-sync-check","category":"anthropic-skill","format":"markdown","content":"---\nname: a2ui-doc-sync-check\ndescription: Auditing codebase implementations for synchronization drift with the user documentation, readmes, and code comments.\n---\n\n# A2UI Code and Documentation Synchronization Check Skill\n\nThis skill guides the process of auditing concrete codebase implementations to verify that they are synchronized with their respective documentation files, codebase READMEs, and inline code comments/docstrings.\n\n---\n\n## **Instructions**\n\n1. **Locate Documentation and Readmes**:\n - Find all user guides, tutorials, and specifications under `docs/` and `specification/`.\n - Find the `README.md` files in each codebase directory.\n\n2. **Audit Readme Commands and Configs**:\n - For each codebase directory, parse the `README.md` to extract setup commands, dependencies, build/test commands, and directory layouts.\n - Cross-reference these details with the codebase's project files (e.g. `package.json`, `pyproject.toml`, `pubspec.yaml`, `Package.swift`).\n - If any command listed in the readme is invalid, deprecated, or has wrong arguments, list it as a discrepancy.\n\n3. **Audit Code-vs-Docs Public API and Settings**:\n - Make sure the glossary is respected. Verify that terms used in code, documentation and blueprints are consistent with [the glossary](../../../docs/public/concepts/glossary.md). If you find deviations, suggest fixes. If you see an important term is used in documentation and/or API, but is missing from the glossary, suggest an update for the glossary.\n - Inspect the codebase's public API entrypoints (classes, interfaces, types, methods).\n - Compare them against any descriptions, structural maps, or code snippets in the `docs/` folder.\n - Look for renamed classes, changed signatures, or removed options that are still described in the docs.\n - If the codebase exposes new settings or flags that are undocumented in `docs/` or the spec guides, log them as missing documentation.\n\n4. **Audit Inline Comments and Docstrings**:\n - Audit inline comments and docstrings (e.g. JSDoc in TS, docstrings in Python, triple-slash comments in Dart/Swift) for public APIs.\n - Flag any mismatch where code parameter names, types, return behaviors, or exceptions thrown deviate from what the docstring claims.\n\n5. **Links and Duplicates**:\n - When an artifact (code, document, issue, PR, comment and so on) is referenced, make sure it has a link.\n - When a glossary term is used - link the first occurrence of the term to the glossary entry if it exists.\n - Make sure there is no duplications of content. If you find some, delete the duplicate and leave a reference.\n\n6. **Conciseness and Clarity**:\n - Verify that documentation and code comments follow the [natural-writing](../natural-writing/SKILL.md) skill, and flag text that breaks its rules.\n\n7. **Format the Report**:\n - Build a Markdown report summarizing the findings:\n - Table of audited directories.\n - **Documentation Drift**: Mismatches between documentation guides (`docs/`) and codebase implementations.\n - **Readme Errors**: Invalid setup, compile, or test commands found in `README.md` files.\n - **Docstring Mismatches**: Outdated parameter names or behaviors described in inline comments.\n - Return this Markdown report as your final response.\n","frontmatter":{"name":"a2ui-doc-sync-check","description":"Auditing codebase implementations for synchronization drift with the user documentation, readmes, and code comments."},"isInternal":false,"tokens":732,"sizeBytes":3296},{"name":"SKILL.md","path":".agents/skills/a2ui-generate-pydantic-models/SKILL.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/a2ui-generate-pydantic-models/SKILL.md","title":"a2ui-generate-pydantic-models","category":"anthropic-skill","format":"markdown","content":"---\nname: a2ui-generate-pydantic-models\ndescription: Automated generator for strongly typed Pydantic v2 data models and basic catalogs across any A2UI protocol version (v0.8, v0.9, v0.9.1, v1.0, etc.).\n---\n\n# A2UI Pydantic Model Generation Skill\n\nThis skill provides an automated code generation tool that produces strongly typed Pydantic v2 data models and basic catalog definitions for `python/a2ui_core` directly from the schemas and catalogs in `specification//`.\n\n---\n\n## Agent Execution Steps\n\nWhen given a prompt like _\"Generate Pydantic model classes for A2UI spec v1.0\"_:\n\n1. **Extract the target version parameter from the prompt** (e.g. `v1.0` -> `v1.0`).\n\n2. **Execute the generator script exactly once for that target version**:\n\n ```bash\n uv run python .agents/skills/a2ui-generate-pydantic-models/scripts/codegen_pydantic.py --version \n ```\n\n _(Replace `` with the single requested version, e.g. `--version v1.0`)_.\n\n3. **Format generated Python code**:\n\n ```bash\n cd python/a2ui_core\n uv run pyink .\n ```\n\n4. **Verify the generated files** by running pytest:\n\n ```bash\n cd python/a2ui_core\n uv run pytest tests/test_codegen_pydantic.py\n ```\n\n5. **Stop and report completion to the user.**\n\n---\n\n## Generated Output Files per Version\n\nWhen executed for a target version `` (e.g. `v1.0` -> `v1_0`), the script generates:\n\n1. **`python/a2ui_core/src/a2ui/core/schema//`**:\n - `constants.py`\n - `common_types.py`: strongly typed shared models and the `COMMON_TYPES_DEFS` manifest, which maps each spec `$defs` name to its symbol in spec order. No spec schema is copied verbatim; the published common types schema is rebuilt from these symbols.\n - Type aliases such as `ComponentId`, `Child`, `ChildList` and the `Dynamic*` unions are registered as `Annotated[..., Field(description=...)]` with the spec descriptions, so the runtime JSON schema generator needs no per-def special cases. Dynamic unions list their members in spec order.\n - When a `Dynamic*` def constrains its function-call branch with a `returnType` const, the branch is `Annotated[FunctionCall, ReturnType(\"\")]`, which validates the return type and emits the spec's `allOf` in both modes. Any other branch shape fails generation.\n - Every model extends `SpecBaseModel` (hand-written in `schema/common_types.py`) and has no generated methods. Keywords that fields cannot produce are declared in the model config as `json_schema_extra=SchemaKeywords(...)`: it drops `additionalProperties` where the spec leaves it out and adds `returnType`, `unevaluatedProperties`, `title`, `allowedParents` and `oneOf` required-alternatives (see `_SPEC_KEYWORDS`). The keywords apply only to the declaring model, not to subclasses. `SpecBaseModel` validates a declared `oneOf` whose branches only list required fields (for example `FunctionResponse`'s `value`/`error`), requiring exactly one branch.\n - Only composition that references the catalog's function union is limited to `spec_schema()` (`SchemaKeywords(..., spec_only=True)`), which the published common types schema uses: v0.9's `FunctionCall` `oneOf`, v1.0's `FunctionCall` `allOf` over `FunctionCommon` and `anyFunction` (`replace=True`, since the spec def is pure composition), and v0.9's precise `args` shape (a schema-only `JsonSchemaAs` annotation requested through the `x-python-type` property override). Catalogs keep the flat model shape there. References inside declared keywords are the markers `def_ref(\"\")` and `catalog_functions()` from the internal `a2ui.core.schema._json_schema` module, which the schema builder resolves to `$ref`s. `FunctionCall` itself is a flat model that validates any call without the catalog.\n - Nested object properties with their own properties become helper models named `` (for example `ComponentCommonMetadata`, `IndexSystemFunctionArgs`, `FunctionResponseError`), which schemas inline. Wrapper unions such as `Action` are `TypeAliasType`s, so fields reference them by def name. Each branch gets a `Wrapper` model, and a branch property that is an object becomes `` (`ActionEvent`, `ActionEventWrapper`, `ActionFunctionCallWrapper`). A generated name that collides with a def, a base symbol or another helper fails generation.\n - A def that the spec leaves open (no `additionalProperties` and no `unevaluatedProperties: false`) allows extra keys. `ComponentCommon` is the exception (`_SUBCLASSED_DEFS`): generated catalog components subclass it and must stay closed.\n - Optional fields are typed `X | None` so they can be absent. `SpecBaseModel` rejects an explicit null for such a field unless `X` accepts null itself (`Any`), under both the spec name and the Python field name; it does not change the JSON schema. Catalog components inherit this rule through `ComponentCommon`. v0.9's `FunctionCall.args` also rejects null values.\n - Primitive defs such as `CallId` are `TypeAliasType`s, so local references keep their `$ref`. References from other documents to a primitive def map to its Python type through `_CROSS_DOCUMENT_REF_TYPES` in `engine.py`.\n - `patternProperties` objects (`Extensions`) are `TypeAliasType`s over a key-checking validator, and their pattern is published in the spec schema and in catalogs. Python's `re` cannot compile `\\p{...}`, so the SDK validates JSON schemas with `a2ui.core.validation.SchemaValidator` (powered by `regex`). The `DynamicValue` literal-object branch carries the spec's `propertyNames` and `not` clauses through a `SchemaKeywords` annotation in both modes.\n - Common types keep `component` properties (`Surface`) and emit required consts without defaults (`skip_component_property` and `required_const_default` on the engine). Spec defaults are emitted as JSON schema `default` values (`schema_defaults`), not as description notes.\n - Common types are generated in strict mode: a schema shape the models would not enforce (an unknown or non-local `$ref`, siblings next to `$ref`/`const`/composition, an unsupported keyword next to `properties`, a required property that is not declared, an empty union) raises instead of loosening validation. Output is deterministic and does not depend on string hashing.\n - `agent_to_renderer.py` / `server_to_client.py`: strongly typed outbound message models and the `AGENT_TO_RENDERER_DEFS` manifest, which maps each spec `$defs` (or v0.8 `properties`) name to its symbol in spec order so `get_agent_to_renderer_schema_map` / `get_agent_to_renderer_schema_json` can rebuild `server_to_client.json` / `agent_to_renderer.json` from the models. Nested payload objects and array item objects become helper models marked with `INLINE_DEF_MARKER` (for example `CreateSurfaceMetadata`, `SurfaceUpdateComponentsItem`), and non-message `$defs` (`Component`, `ComponentsList`) are emitted as `TypeAliasType`s with `SchemaKeywords`.\n - `renderer_to_agent.py` / `client_to_server.py`\n - `renderer_capabilities.py` / `client_capabilities.py`\n - `agent_capabilities.py` / `server_capabilities.py` (when present in spec)\n - `catalog_definition.py` (when present in spec)\n - `__init__.py`\n\n2. **`python/a2ui_core/src/a2ui/core/basic_catalog//`**:\n - `components.py` (strongly typed components & `ModelComponentApi` registrations)\n - `function_apis.py` (strongly typed function schemas & `FunctionApi` classes)\n - `styles.py` (theme schema, generated when theme is defined in catalog)\n - `__init__.py`\n - The models and the generated `BasicCatalog` carry everything `Catalog.to_json()` needs to rebuild the published catalog document from them, with no catalog JSON copied into Python or read at runtime:\n - `BasicCatalog` passes the document's top-level fields to `Catalog`: `$schema`, `$id`, `title`, `description`, `protocolVersion` (None when the document declares none), `catalogId` when it declares none, `instructions`, where it writes its theme (`theme_location`), its unions (`union_defs`, which must list the catalog's entries) and the document its common types references point into (`common_types_uri`). The theme is passed as `theme_model`.\n - Without common types (v0.8), nested objects become models that keep the document's shapes: two nested objects of different shapes never share a model (the later one is prefixed with its component or parent model, for example `SliderValueItem`), and their descriptions stay on the fields, with line breaks, rather than becoming docstrings. `Catalog.to_json()` writes them inline, as the v0.8 document does.\n - For versions with a common types schema (v0.9+), the models carry everything `Catalog.validation_schema` and `Catalog.to_json()` need to rebuild the specification's `catalog.json` shape from them:\n - A component's `allOf` references to common types defs (for example `Checkable`) become base classes, and catalog defs (`CatalogComponentCommon`) become base models. A component with more than one base sets `extra=\"forbid\"`, because Pydantic would otherwise inherit an open base's config. A component description becomes the class docstring and fails generation if it cannot be one.\n - A function's description becomes the `FunctionApi.description` attribute. Keywords on the `args` object that fields cannot produce (`unevaluatedProperties`, `additionalProperties`, required-alternative `anyOf`) are declared with `SchemaKeywords` as the model's `json_schema_extra`, and an unknown keyword fails generation.\n - Field constraints (`minItems`, `minimum`, ...) are emitted as `Field` arguments, so they are validated and published; `format` and `default` are published through `json_schema_extra`. An `allOf` member that only adds keywords becomes a `SpecAllOf` annotation.\n - The conformance cases `test_v08_basic_catalog_to_json`, `test_v09_basic_catalog_to_json` and `test_v10_basic_catalog_to_json`, and `python/a2ui_core/tests/test_basic_catalog_documents.py`, compare `BasicCatalog().to_json()` with the published files, so any drift fails the tests.\n\n3. **`python/a2ui_core/src/a2ui/core/schema/__init__.py`**:\n - Registers the version in `A2uiProtocolVersion` enum and updates envelope unions.\n","frontmatter":{"name":"a2ui-generate-pydantic-models","description":"Automated generator for strongly typed Pydantic v2 data models and basic catalogs across any A2UI protocol version (v0.8, v0.9, v0.9.1, v1.0, etc.)."},"isInternal":false,"tokens":2372,"sizeBytes":10250},{"name":"SKILL.md","path":".agents/skills/a2ui-implement-new-sdks-for-client-language/SKILL.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/a2ui-implement-new-sdks-for-client-language/SKILL.md","title":"a2ui-implement-new-sdks-for-client-language","category":"anthropic-skill","format":"markdown","content":"---\nname: a2ui-implement-new-sdks-for-client-language\ndescription: Step-by-step phased instructions for building new A2UI Core SDKs, Framework Adapters, and Inference SDKs from scratch in any client language.\n---\n\n# A2UI SDK Implementation Guide (Phased Execution)\n\nThis skill provides expert instructions and sequences for AI agents or contributors tasked with implementing A2UI Core SDKs, Framework Adapters, or Agent/Inference SDKs in a new programming language or UI framework.\n\n---\n\n## **1. Core State SDK Phases**\n\nIf you are building a new **Core SDK** (e.g., in Rust, Swift, Go, or C++), you must follow this sequence of phases:\n\n### **Phase 1: Context & Schemas Ingestion**\n\nThoroughly review:\n\n- `blueprints/modules/a2ui_core.blueprint.md` (for state and message structures).\n- `specification/v1_0/json/common_types.json` (dynamic binding schemas).\n- `specification/v1_0/json/server_to_client.json` (message envelopes).\n- `catalogs/basic/v1/catalog.json` (target components catalog).\n\n### **Phase 2: Technical Architecture Planning**\n\nCreate a detailed, local architectural proposal detailing:\n\n- **Dependencies**: Which Schema library and Observable/Reactive library will you use? Note that the reactive library must support both discrete event subscription and stateful, signal-like data streams (e.g., BehaviorSubject/Signal).\n- **Component APIs**: How will you define the `ComponentApi` interface in this language?\n- **Binding Strategy**: How will you structure the abstract Core Binder Layer?\n- _STOP and obtain human reviewer approval on this plan before writing code._\n\n### **Phase 3: Core Model Layer**\n\nImplement the framework-agnostic data and processor layers:\n\n1. **Observables & Signals**: Implement multi-cast reactive streams with clear unsubscribe mechanism to prevent leaks.\n2. **Protocol Structures**: Create strictly-typed native classes/structs representing `A2uiMessage` envelopes and client capabilities with serialization/deserialization.\n3. **DataModel & JSON Pointers**: Implement relative/absolute path resolution, auto-vivification (auto-typing intermediate segments), and bubble/cascade path change notifications.\n4. **Core State Models**: Implement `ComponentModel`, `SurfaceComponentsModel`, `SurfaceModel`, and `SurfaceGroupModel`.\n5. **Context Mapping**: Implement `DataContext` and `ComponentContext`.\n6. **MessageProcessor**: Ingest incoming messages and mutate the state models. Generate `inlineCatalogs` client capabilities.\n7. **Verification**: Write comprehensive unit tests for pointer cascading, JSON deserialization/validation, and message dispatching.\n\n### **Phase 4: Foundational Basic Catalog Support**\n\nBootstrap support for the Basic Catalog:\n\n- **Foundational Components**: Define the pure API schemas and Binders for: `Text`, `Row`, `Column`, `Button`, and `TextField`.\n- **Foundational Functions**: Implement `formatString` to interpret `${expression}` syntaxes, supporting recursive token evaluations and reactive coercion.\n- **Verification**: Ensure properties update reactively when underlying data paths emit notifications.\n\n### **Phase 5: Complete Basic Catalog Support**\n\n- **Full Components & Binders**: Define core binders for all other components in `basic/catalog.json`.\n- **Full Functions**: Implement remaining basic mathematical, logical, and array operations.\n- **Validation**: Ensure strict type coercion rules are satisfied and memory disposals work flawlessly.\n\n---\n\n## **2. Framework Adapter SDK Phases**\n\nIf you are building a new **UI Framework Adapter / Renderer** (e.g., in Flutter/Dart, SwiftUI, Jetpack Compose, Vue, or Svelte), follow this sequence:\n\n### **Phase 1: Ingestion & Core Integration**\n\nReview:\n\n- `blueprints/modules/a2ui_framework_adapter.blueprint.md` (View and rendering architecture).\n- `catalogs/basic/v1/basic_catalog_implementation_guide.md` (spacing, alignment, and typography specifications).\n\n### **Phase 2: Architectural Plan**\n\nDraft a plan specifying:\n\n- **Component Registry**: How components are dynamically resolved and instantiated.\n- **Surface Widget**: How the root canvas mounts and recurses through the layout tree starting at `root`.\n- **Observer/State Bridge**: Which Strategy (Direct, Predefined Binders, or Automated wrappers) will connect core signals to native views.\n- _STOP and obtain human reviewer approval on this plan._\n\n### **Phase 3: Adapter & Lifecycle Layer**\n\n- Implement `ComponentImplementation` base traits/classes.\n- Implement the framework-native `Surface` entrypoint widget.\n- Implement subscription management: lazy-subscribing only on mount, handling path stability updates, and strictly calling `dispose()` on unmount.\n\n### **Phase 4: Bootstrapping Basic Catalog Rendering**\n\n- Build native visual elements for: `Text`, `Row`, `Column`, `Button`, and `TextField`.\n- Bundle these elements into the first framework catalog adapter.\n- Verify reactive layout properties dynamically.\n\n### **Phase 5: Gallery Application Milestone**\n\nBuild the **Gallery App** as a testing playground with:\n\n- Left Column: Sample navigation.\n- Center Column: Surface preview, JSON message stream, and step-by-step interactive message stepper.\n- Right Column: Live data model inspect pane and action logger.\n- Load the 5 foundational verification examples: `00_simple-text.json`, `00_row-layout.json`, `00_complex-layout.json`, `00_interactive-button.json`, and `00_simple-login-form.json`.\n- _STOP and obtain human reviewer approval of the UI and visual rendering performance._\n\n### **Phase 6: Full Catalog Support**\n\n- Implement all remaining widgets (e.g. Card, Image, List, etc.) and validation traits like `Checkable`.\n- Update the Gallery App to support all official examples in `catalogs/basic/v1/examples/`.\n- Run visual parity and event action tests to verify correctness.\n","frontmatter":{"name":"a2ui-implement-new-sdks-for-client-language","description":"Step-by-step phased instructions for building new A2UI Core SDKs, Framework Adapters, and Inference SDKs from scratch in any client language."},"isInternal":false,"tokens":1222,"sizeBytes":5808},{"name":"README.md","path":".agents/skills/a2ui-issue-triage/README.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/a2ui-issue-triage/README.md","title":"A2ui-issue-triage Skill","category":"anthropic-skill","format":"markdown","content":"# A2ui-issue-triage Skill\n\nPath: `.agents/skills/a2ui-issue-triage/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/a2ui-issue-triage/README.md)","tokens":300,"sizeBytes":208},{"name":"triage_criteria.md","path":".agents/skills/a2ui-issue-triage/references/triage_criteria.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/a2ui-issue-triage/references/triage_criteria.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# References Skill\n\nPath: `.agents/skills/a2ui-issue-triage/references/triage_criteria.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/a2ui-issue-triage/references/triage_criteria.md)","tokens":300,"sizeBytes":241},{"name":"SKILL.md","path":".agents/skills/a2ui-issue-triage/SKILL.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/a2ui-issue-triage/SKILL.md","title":"a2ui-issue-triage","category":"anthropic-skill","format":"markdown","content":"---\nname: a2ui-issue-triage\ndescription: Automates the triage of GitHub issues in the A2UI repository. Helps the oncall engineer by fetching untriaged issues, generating AI-suggested priorities, assignees, and responses, launching a local review dashboard, and bulk-applying approved decisions to GitHub. Use when tasked with triaging new GitHub issues or managing the repository backlog.\n---\n\n# A2UI GitHub Issue Triage Skill\n\nThis skill guides the process of fetching, analyzing, reviewing, and applying triage decisions to GitHub issues in the A2UI repository using a local interactive dashboard.\n\n> [!IMPORTANT]\n> **WRITING GUIDELINES**\n> When drafting replies, explanations, or any prose, refer to the [natural-writing](../natural-writing/SKILL.md) skill to ensure clarity, accuracy, and tone.\n\n---\n\n## Workflow\n\nFollow these steps to triage new or backlog issues:\n\n### Step 1: Fetch Untriaged Issues\n\nUse the fetch script to retrieve all open issues lacking a priority label (`P0`, `P1`, `P2`, `P3`, `P4`) in the A2UI repository.\n\n1. Run the fetch script to download the issues to a raw JSON file in your conversation-specific scratch directory:\n `python3 .agents/skills/a2ui-issue-triage/scripts/fetch_issues.py --repo \"a2ui-project/a2ui\" --output-file \"/brain//scratch/raw_issues.json\"`\n\n---\n\n### Step 2: Analyze and Suggest Triage\n\nProcess the raw issues and generate recommended triage fields based on the project's triage criteria.\n\n1. Read the triage criteria reference document: [triage_criteria.md](references/triage_criteria.md) and repository canonical templates: [triage-templates.md](../../../docs/contributing/triage-templates.md).\n2. For each issue in `raw_issues.json`, evaluate its description and comments to determine:\n - **Priority**: `P0` (Urgent), `P1` (High), `P2` (Medium), `P3` (Low), `P4` (Unplanned/Out of Scope), or `None`. `P0` and `P1` require assignees.\n - **Assignee**: Recommended owner based on the affected component or area.\n - **Action**: `investigate`, `assign_and_fix`, `needs_info`, `backlog`, `close_duplicate`, `close_invalid`, or `close_resolved`.\n - **Labels**: Applicable repository labels (e.g. `type: bug`, `component: lit renderer`, `status: first-line-handled`, `status: waiting-for-author-response`).\n - **Reply**: A polite, structured draft response addressing the author using canonical templates.\n3. If an issue is a potential duplicate, perform at most three targeted GitHub searches to find matching canonical issues before suggesting `close_duplicate`.\n4. **Natively Orchestrate Subagents**: Instead of running a Python script to spawn subagents (which can fail due to local workstation gRPC credential policies), the parent agent should natively orchestrate the parallel evaluations:\n - Load the first N issues (defaulting to 10, or as requested) from `raw_issues.json`.\n - Call the `invoke_subagent` tool in parallel for those issues. Prompt each subagent to analyze its assigned issue against the guidelines in [triage_criteria.md](references/triage_criteria.md) and return a structured JSON block containing `priority`, `action`, `labels`, and `reply`.\n - Once all subagents report back, compile their recommendations into the standard schema:\n - Map component labels to suggested assignees using git log history if necessary, and include a short sentence in `assignee_reason` explaining why they were chosen (e.g., \"Suggesting gspencer because they recently modified related code\").\n - Inject `total_issues_count` (preserving the total count from the raw issues JSON).\n - Save the final compiled payload to `issues_to_triage.json` in the scratch directory.\n\n---\n\n### Step 3: Launch Review Dashboard\n\nLaunch the interactive web dashboard to allow the oncall engineer to review and refine the suggested triages.\n\n1. Start the local server as a background task, pointing it to your scratch directory:\n `python3 .agents/skills/a2ui-issue-triage/scripts/launch_dashboard.py --data-file \"/brain//scratch/issues_to_triage.json\" --output-file \"/brain//scratch/triage_decisions.json\"`\n Set `WaitMsBeforeAsync` to `1000` so the server runs in the background.\n2. **Wait for Completion**: Stop calling tools and go idle. The launcher will automatically open the browser for the user and block until they click \"Apply Triages\" or \"Abort\". Once the user acts, the background task will complete, and you will receive a notification with the exit status.\n3. **Verify Exit Status**:\n - If the task exited with status `0` (approved), proceed to apply the decisions.\n - If the task exited with a non-zero status (abort), don't modify any issues. You MUST STOP and ask the user for further instructions.\n\n---\n\n### Step 4: Apply Decisions to GitHub\n\nOnce the dashboard task exits successfully, **Execute Approved Decisions**: Run the apply script to update the approved labels, assignees, and comments on GitHub:\n\n`python3 .agents/skills/a2ui-issue-triage/scripts/apply_triage.py --decisions-file \"/brain//scratch/triage_decisions.json\"`\n\n---\n\n## Bundled Resources\n\n- **[triage_criteria.md](references/triage_criteria.md)**: Authoritative guide for classifying issues, assigning priorities, and drafting response messages.\n- **`scripts/fetch_issues.py`**: Script to query open, untriaged issues via the GitHub CLI.\n- **`scripts/suggest_triage.py`**: Helper script to generate initial triage suggestions.\n- **`scripts/launch_dashboard.py`**: Local HTTP server that opens the interactive web dashboard in the user's browser.\n- **`assets/triage_dashboard.html`**: HTML/CSS/JS template for the triage review interface.\n- **`scripts/apply_triage.py`**: Script to apply finalized triage decisions to GitHub.\n","frontmatter":{"name":"a2ui-issue-triage","description":"Automates the triage of GitHub issues in the A2UI repository. Helps the oncall engineer by fetching untriaged issues, generating AI-suggested priorities, assignees, and responses, launching a local review dashboard, and bulk-applying approved decisions to GitHub. Use when tasked with triaging new GitHub issues or managing the repository backlog."},"isInternal":false,"tokens":1329,"sizeBytes":5801},{"name":"SKILL.md","path":".agents/skills/a2ui-release-python/SKILL.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/a2ui-release-python/SKILL.md","title":"a2ui-release-python","category":"anthropic-skill","format":"markdown","content":"---\nname: a2ui-release-python\ndescription: Releases the Python SDKs (a2ui-core, a2ui-agent-sdk, a2ui-a2a, a2ui-adk) to PyPI by running preflight checks, dispatching the release workflow as a dry run, confirming with the maintainer, publishing, and following the changelog pull request through to merge. Use when asked to cut, publish, or release a Python SDK version.\n---\n\n# Releasing the A2UI Python SDKs\n\nThis skill turns a one-line request such as _\"release a2ui-core patch\"_ or\n_\"release the Python SDKs\"_ into the full release sequence.\n\nPublishing is done by the\n[Release Python SDKs](../../../.github/workflows/release-pypi.yml) workflow. This\nskill does not reimplement any of it. Its job is the part the workflow cannot do\nfor itself: choosing the bump, catching the problems that a workflow run would\ndiscover too late, and following through afterwards.\n\nBackground for anything not covered here:\n[docs/contributing/release.md](../../../docs/contributing/release.md).\n\n> [!CAUTION]\n> **Publishing to PyPI is irreversible.** A version can be yanked but never\n> reused or deleted. Step 5 is a mandatory stop. Never dispatch a run with\n> `dry_run: false` without an explicit go-ahead from the maintainer in the\n> current conversation.\n\n### What runs where\n\n**The workflow performs the release. Nothing here does.** Building, tagging,\npushing tags, staging in the Artifact Registry and triggering the Exit Gate all\nhappen inside `release-pypi.yml`, and only there. It could not be otherwise: the\nExit Gate authenticates by matching the OIDC claim\n`…/release-pypi.yml@refs/heads/main`, so a local upload has no credentials to\nuse.\n\n| Run locally | Run by the workflow |\n| :--------------------------------------------- | :------------------------------------------------ |\n| `release_version.py notes` | `release_version.py plan` (authoritative) |\n| `release_version.py plan` (preview only) | `release_version.py check` |\n| `release_version.py check` (preview only) | `release_version.py cut-changelog` |\n| `gh workflow run`, `gh run view`, `gh pr list` | `release_artifacts.py`, `confirm_pypi.py` |\n| | `uv build`, `twine upload`, `git tag`, `git push` |\n\nThe local calls are limited to the read-only subcommands `notes`, `next`,\n`current`, `tag`, `plan` and `check`. They exist to answer two questions before\nspending a CI run: is there anything to release, and will preflight reject it.\n\n> [!IMPORTANT]\n> A local `plan` is a **prediction**, not the release. It is computed from the\n> tags in the local checkout, so it is only as current as the last fetch — which\n> is why Step 2 fetches first. The plan the workflow computes is the one that\n> counts, and Step 4 reads it back out of the run before anyone approves it.\n\nNever run `cut-changelog --write`, `git tag`, `git push`, `uv build` or `twine`\nby hand to perform a release. If the workflow cannot do it, fix the workflow.\n\n> [!IMPORTANT]\n> One exception, and it is deliberate: **the changelog pull request has to be\n> opened by a person, not by the workflow.** GitHub does not start workflow runs\n> for events caused by `GITHUB_TOKEN`, so a pull request the workflow opened\n> would never get the required checks and could never be merged. The workflow\n> pushes the branch; Step 7 opens the pull request.\n\n## Step 1: Check environment prerequisites\n\nCheck that your local environment meets these prerequisites before proceeding.\nThe preflight check in Step 3 (`release_version.py check`) also validates these\nautomatically and stops with an `Action needed:` message for each one that\nfails. They are skipped in GitHub Actions, where they do not apply.\n\n1. **An a2ui checkout.** Run from your clone of `a2ui-project/a2ui`. The script\n finds the repository root itself, so a subdirectory works (it warns), but\n the commands below use paths relative to the root.\n2. **Python 3.11+.** The script reads `pyproject.toml` with the standard\n library `tomllib`. If your system `python3` is older, run it through the\n project toolchain instead: `uv run python .github/scripts/release_version.py\n...`.\n3. **GitHub CLI (`gh`)**, installed, authenticated with `github.com`, and with\n write access to `a2ui-project/a2ui`. It dispatches and watches the workflow\n and opens the changelog pull request.\n4. **Git identity.** `git config user.name` and `git config user.email` must be\n set, so the changelog commit and pull request pass CLA verification.\n5. **A remote that points at `a2ui-project/a2ui`.** It may be called `origin`\n in a direct clone or `upstream` beside a fork; the script finds it by URL.\n The commands below call it `${REMOTE}`:\n\n ```bash\n REMOTE=$(git remote -v | awk '/a2ui-project\\/a2ui(\\.git)?\\/? \\(fetch\\)/ {print $1; exit}')\n ```\n\n---\n\n## Step 2: Work out what is being released\n\nTwo things are needed: `PACKAGE` and `BUMP` (`patch`, `minor`, or `major`).\n`PACKAGE` names the packages to release, either as a comma-separated list of\npackage names or as `all`:\n\n- One package: `a2ui-agent-sdk`\n- Several packages: `a2ui-a2a,a2ui-adk`\n- Every package: `all` (`a2ui-core`, `a2ui-agent-sdk`, `a2ui-a2a`, `a2ui-adk`)\n\nThe workflow publishes the listed packages in dependency order (`a2ui-core`,\n`a2ui-agent-sdk`, `a2ui-a2a`, `a2ui-adk`), whatever order they are listed in.\nDerive `PACKAGE` and `BUMP` from the changelogs. Never infer them from the\nphrasing of the request.\n\nFetch first. Versions are derived from tags, so every number below is wrong if\nthe checkout is behind:\n\n```bash\ngit fetch \"${REMOTE}\" main --tags\n```\n\n```bash\nfor package in a2ui-core a2ui-agent-sdk a2ui-a2a a2ui-adk; do\n echo \"== ${package}\"\n python3 .github/scripts/release_version.py notes --package \"${package}\"\ndone\n```\n\n**Choose the packages.** Release only those with a non-empty `## Unreleased`.\nEmpty output means that package has nothing to release, whatever was asked for.\nA plural request such as _\"release the Python SDKs\"_ does not mean `all`. List\nexactly the packages with pending entries, for example\n`a2ui-agent-sdk,a2ui-a2a`. If only one has pending entries, that one is the\nrelease. If none does, stop and say so.\n\nCheck the exit status, not just the output. The two failure shapes are\ndifferent answers:\n\n| Result | Meaning | Do |\n| :------------------------- | :---------------------------------------------------------------- | :----------------------------------- |\n| exit 0, output | Entries pending | Release this package |\n| exit 0, no output | `## Unreleased` is empty | Skip this package |\n| exit 1, `error:` on stderr | Changelog is malformed, usually a missing `## Unreleased` heading | Stop. Report it and do not dispatch. |\n\n> [!NOTE]\n> Dispatching a package whose `## Unreleased` is empty is not dangerous, just wasteful. The\n> plan builds, then preflight rejects the empty package and the run fails\n> several minutes in. The check above costs a second.\n\n**Choose the bump.** Read the entries. Fixes only means `patch` and new\nfeatures mean `minor`. A breaking change means `minor` while the package is\nbelow 1.0, and `major` from 1.0 on. Preview the result with `plan`,\nwhich returns exactly what the workflow will compute — version, tag and release\nnotes for every selected package:\n\n```bash\npython3 .github/scripts/release_version.py plan --package \"${PACKAGE}\" --bump \"${BUMP}\"\n```\n\n> [!IMPORTANT]\n> **One run applies one bump level to every listed package.** The workflow\n> takes a single `bump` input, so `build_plan` raises every version by the same\n> amount. When the packages warrant different levels — say fixes in\n> `a2ui-core` and a feature in `a2ui-agent-sdk` — there is no single right\n> answer. Put the choice to the maintainer:\n>\n> - **Take the higher level for every listed package.** One release, one\n> changelog pull request. The cost is an over-bumped version on the quieter\n> packages.\n> - **Run one release per bump level.** Correct versioning, but the changelog\n> pull request from each run must be **merged before starting the next**, or\n> the Step 3 guard will block it. Release in dependency order: `a2ui-core`,\n> `a2ui-agent-sdk`, `a2ui-a2a`, `a2ui-adk`.\n\n> [!IMPORTANT]\n> **A minor or major `a2ui-core` bump may need a pin change first.**\n> `a2ui-agent-sdk` declares a range such as `a2ui-core>=0.3.0,<0.4.0` in\n> [a2ui_agent/pyproject.toml](../../../python/a2ui_agent/pyproject.toml). If\n> the proposed `a2ui-core` version falls outside it, widen the pin in its own\n> pull request and **merge it to `main` before dispatching**. The workflow\n> releases `main` as it is and cannot change package files during the run.\n> Step 3 rejects the release until this is done.\n>\n> The same applies down the chain: `a2ui-a2a` and `a2ui-adk` pin\n> `a2ui-agent-sdk` in their `pyproject.toml`, and `a2ui-adk` pins `a2ui-a2a`\n> in its `a2a` extra. A new version of a package must fall inside every pin on\n> it.\n\n> [!IMPORTANT]\n> **A dependent needs its dependencies on PyPI.** Releasing `a2ui-a2a` or\n> `a2ui-adk` on its own requires the released `a2ui-agent-sdk` (and, for\n> `a2ui-adk`, `a2ui-a2a`) to satisfy its pins already. If it does not, release\n> the dependency first, or list it in the same run. Step 3 reports\n> this as \"has not been released yet\" or \"requires ..., but the latest release\n> ... is ...\".\n>\n> **First release of a brand-new package.** A package with no tag yet starts\n> from `0.0.0`, so use a `minor` bump to release `0.1.0`. Before its first\n> release, the package name must be added to the OSS Exit Gate allowlist for\n> `a2ui/pypi` and registered as a **Pending Publisher** on\n> `https://pypi.org/manage/account/publishing/` under the **Google** tab with\n> email `a2ui-py@oss-exit-gate-prod.iam.gserviceaccount.com` and an empty\n> subject (see `go/a2ui-release#pypi`). PyPI indexes Google Cloud Pending\n> Publishers uniquely by `(email, sub)`, so **only one Pending Publisher can be\n> registered at a time**. Do not release two brand-new packages in the same\n> manifest: register and publish them one at a time so the first upload\n> promotes its Pending Publisher to a project-scoped Trusted Publisher before\n> registering the second.\n\nPut the proposal to the maintainer with `ask_question`, showing the pending\nentries and the resulting versions, and let them correct it.\n\n---\n\n## Step 3: Preflight locally\n\nThese checks cost seconds and catch the failures that are expensive to hit\nmid-run. Run all of them before dispatching anything.\n\n**1. The environment and the checkout.** `check` runs these for you (see\nStep 1: Check environment prerequisites); this is what it looks for and why:\n\n- **No outstanding changelog branch** from a previous release on `${REMOTE}`.\n Until the last release's changelog lands, its entries are still under\n `## Unreleased`, and this release would repeat them. It checks the branch,\n not the pull request, because the release stops at the branch and there may\n be no pull request yet. The repository deletes branches on merge, so no\n branch means the last changelog landed. If one is found, get that change\n merged (open the pull request if nobody has), then start over from Step 2,\n because the pending entries will have changed.\n- **The released packages match `${REMOTE}/main`.** The workflow builds from\n `main`, so `python/a2ui_core`, `python/a2ui_agent`, `python/a2ui_a2a` and\n `python/a2ui_adk` must be identical to it.\n Uncommitted edits, or a local commit that is not merged yet (a widened pin,\n say), would make the local preview describe a release that is not the one\n that will go out. Other paths in the checkout do not matter.\n\nIf it reports any of these, or any of the Environment Prerequisites, stop and\nsay what was found.\n\n**2. The repository's own preflight passes.** The package checks (changelog,\ntag, and pin) are the ones the workflow runs, so a failure in them here is a\nfailure there:\n\n```bash\n# Check using bump level (comma-separated package names, or 'all'):\npython3 .github/scripts/release_version.py check --package \"${PACKAGE}\" --bump \"${BUMP}\"\n\n# Or check a specific version directly (single package only):\npython3 .github/scripts/release_version.py check --package \"${PACKAGE}\" --version \"${VERSION}\"\n```\n\nIt rejects an empty `## Unreleased`, a version that already has a tag, a version\noutside the range that another package pins it to, and a dependency on another\npackage of this repository that no released version (or no version in the same\nrun) satisfies. With several packages and `--bump`, it evaluates every listed\npackage and their cross-dependency pins in a single step.\n\nIf preflight reports a pin problem, stop: see the pin notes in Step 2.\n\n---\n\n## Step 4: Dry run\n\nA dry run builds and stages the artifacts in the Exit Gate Artifact Registry,\nremoves them again, and pushes nothing.\n\n```bash\ngh workflow run release-pypi.yml --repo a2ui-project/a2ui --ref main \\\n -f package=\"${PACKAGE}\" -f bump=\"${BUMP}\" -f dry_run=true\n```\n\nWait a few seconds, then find the run and watch it:\n\n```bash\ngh run list --repo a2ui-project/a2ui --workflow=release-pypi.yml --limit 1 \\\n --json databaseId,status,url\ngh run watch \"${RUN_ID}\" --repo a2ui-project/a2ui --exit-status\n```\n\n> [!TIP]\n> Use the full `databaseId`. A truncated run ID returns 404.\n\nIf it fails, read the failing step's log and consult Troubleshooting below\nbefore retrying.\n\nWhen it passes, read back the plan the run actually computed. The dry run does\nnot upload the plan artifact, and step summaries are not available over the API,\nbut the plan step prints the JSON into the log:\n\n```bash\ngh run view \"${RUN_ID}\" --repo a2ui-project/a2ui --log \\\n | grep -A 20 'Build the release plan'\n```\n\nCompare it against the local `plan` output from Step 2. They are computed the\nsame way and should agree. If they differ, a tag landed in between — stop and\nwork out why before going any further.\n\n---\n\n## Step 5: Confirm with the maintainer\n\n**Stop here.** Show the maintainer:\n\n- the exact versions and tags from the dry run's plan,\n- the changelog entries that will become the release notes,\n- that the dry run passed.\n\nQuote the version numbers in full, for example `a2ui-agent-sdk 0.7.0`. Do not\ndescribe the release only as \"a minor bump\" — the bump level is the input, the\nversion is the irreversible consequence, and it is the version the maintainer\nneeds to approve.\n\nThen ask for explicit confirmation to publish. Proceed only on a clear yes.\n\n---\n\n## Step 6: Publish\n\n```bash\nAUTHOR_NAME=$(git config user.name)\nAUTHOR_EMAIL=$(git config user.email)\ngh workflow run release-pypi.yml --repo a2ui-project/a2ui --ref main \\\n -f package=\"${PACKAGE}\" -f bump=\"${BUMP}\" -f dry_run=false \\\n -f author_name=\"${AUTHOR_NAME}\" -f author_email=\"${AUTHOR_EMAIL}\"\n```\n\nWatch it as in Step 4. The run pushes the tags, stages the artifacts, uploads\nthe manifest that triggers the Exit Gate, and creates the GitHub releases.\n\nFour jobs follow:\n\n| Job | What it does | If it fails |\n| :---------- | :----------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- |\n| `build` | Runs tests and builds distributions | Test failure or malformed distribution. See Troubleshooting. |\n| `release` | Stages, tags, and triggers publishing | Real failure. See Troubleshooting. |\n| `confirm` | Polls PyPI, then links the GitHub releases | A timeout is not a failure. The hourly [Confirm PyPI publication](../../../.github/workflows/release-verify-pypi.yml) workflow finishes the job. |\n| `changelog` | Pushes the changelog branch | Publishing already succeeded. Cut the changelog by hand and open the PR yourself. |\n\n> [!IMPORTANT]\n> **The run stays active for several minutes after `release` goes green, and\n> that is normal.** Triggering the Exit Gate is not publishing. The Exit Gate\n> works asynchronously and reports only by email, so the `confirm` job sits and\n> polls PyPI every 30 seconds for up to 20 minutes waiting for the version to\n> appear.\n>\n> `gh run watch` blocks until all three jobs finish, so it is the wait. Let it\n> run. Do not poll PyPI in a loop alongside it, and do not report the release as\n> finished — or as failed — while `confirm` is still in progress.\n\n---\n\n## Step 7: Follow through\n\nA release is not done when the workflow goes green.\n\n1. **Confirm the version is live.** The waiting has already happened on the\n runner, so read the `confirm` job's outcome rather than starting a fresh\n wait:\n\n - **`confirm` succeeded** — the version is on PyPI and the GitHub releases\n have been updated with links. Verify once and move on:\n\n ```bash\n curl -s -o /dev/null -w '%{http_code}\\n' \"https://pypi.org/pypi/${PYPI_NAME}/${VERSION}/json\"\n ```\n\n `200` confirms it. A `404` here, after `confirm` reported success, is a CDN\n lag of a minute or two — wait briefly and check again.\n\n - **`confirm` timed out** — publishing took longer than 20 minutes. **This is\n not a failed release.** The artifacts are staged and the Exit Gate still\n has them. Do not re-run the release, and do not try to publish the version\n again: that would burn a version number. Tell the maintainer it is\n outstanding, and leave it to the hourly\n [Confirm PyPI publication](../../../.github/workflows/release-verify-pypi.yml)\n workflow, which finds the release by its pending marker and links it once\n PyPI catches up. The Exit Gate also emails\n `a2ui-core-working-group@google.com` with the outcome either way.\n\n - **`confirm` failed for another reason** — read the log. The publish itself\n may still have succeeded, so check PyPI before concluding anything.\n\n2. **Open the changelog pull request and get it merged.** The release pushed the\n branch but deliberately did not open the pull request — see \"What runs\n where\". Open it yourself:\n\n ```bash\n BRANCH=$(git ls-remote --heads \"${REMOTE}\" 'release/changelog-*' \\\n | sed 's#.*refs/heads/##')\n gh pr create --repo a2ui-project/a2ui --base main --head \"$BRANCH\" \\\n --title \"chore(release): changelog for ${RELEASED}\" \\\n --body \"Moves the \\`## Unreleased\\` entries under the released versions.\"\n ```\n\n Check the diff touches only `CHANGELOG.md` files, then ask the maintainer to\n review it. Do not leave it open: Step 3 blocks the next release until the\n branch is gone.\n\n3. **Report** the published versions, the GitHub release links, and the\n changelog pull request link.\n\n---\n\n## Troubleshooting\n\n**`could not find any workflows named release-pypi.yml`** — the workflow is only\ndispatchable once it is on `main`. Check it has merged.\n\n**HTTP 403 from Artifact Registry** — the Exit Gate allowlists\n`a2ui-project/a2ui` only. This is the expected result on a fork, and not a bug.\nOn the real repository it means the builder identity no longer matches; see\n`go/oss-exit-gate-builders`.\n\n**`Permission denied` or a failed OIDC exchange** — the Exit Gate matches the\nworkflow path and branch exactly:\n\n```\ngithub_workflow:a2ui-project/a2ui/.github/workflows/release-pypi.yml@refs/heads/main\n```\n\nRenaming or moving the workflow file breaks releases until the internal config\nis updated. It also cannot be triggered from a branch or a tag, only `main`.\n\n**`... is already on PyPI`** — the version was published previously. It cannot be\nrepublished. Work out why the tag series and PyPI disagree before retrying.\n\n**`One or more packages are not in the project's allowlist` or `400 Non-user identities cannot create new projects` in Exit Gate logs**: a brand-new package name must be added to the OSS Exit Gate allowlist and registered as a Pending Publisher on `https://pypi.org/manage/account/publishing/` before its first release. Because PyPI allows only one Pending Publisher at a time for `a2ui-py@oss-exit-gate-prod.iam.gserviceaccount.com`, publish brand-new packages one at a time. See [docs/contributing/release.md](../../../docs/contributing/release.md#releasing-a-new-package-for-the-first-time) and `go/a2ui-release#pypi`.\n\n**A dry run or failed staging left artifacts behind** — the cleanup step runs\neven on partial failure, but if it was itself skipped, remove the staged version\nby hand:\n\n```bash\ngcloud artifacts versions delete \"${VERSION}\" --package=\"${PYPI_NAME}\" \\\n --repository=a2ui--pypi --location=us --project=oss-exit-gate-prod --quiet\n```\n\n---\n\n## Rules\n\n- Never edit a version by hand. Versions come from git tags via `hatch-vcs`, and\n the workflow verifies the built artifacts against the version it planned.\n- Never push tags or run the release scripts locally to publish. The scripts\n under `.github/scripts/` are safe to run read-only for `notes`, `next`,\n `current`, `tag`, and `check`. Everything else belongs to the workflow.\n- Never dispatch `dry_run: false` without the Step 5 confirmation.\n- If the maintainer asks to skip the dry run, push back once: it is the only\n rehearsal before an irreversible publish. Defer if they insist.\n","frontmatter":{"name":"a2ui-release-python","description":"Releases the Python SDKs (a2ui-core, a2ui-agent-sdk, a2ui-a2a, a2ui-adk) to PyPI by running preflight checks, dispatching the release workflow as a dry run, confirming with the maintainer, publishing, and following the changelog pull request through to merge. Use when asked to cut, publish, or release a Python SDK version."},"isInternal":false,"tokens":5310,"sizeBytes":21875},{"name":"pr-description-template.md","path":".agents/skills/a2ui-remediate-problem/references/pr-description-template.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/a2ui-remediate-problem/references/pr-description-template.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# References Skill\n\nPath: `.agents/skills/a2ui-remediate-problem/references/pr-description-template.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/a2ui-remediate-problem/references/pr-description-template.md)","tokens":300,"sizeBytes":267},{"name":"SKILL.md","path":".agents/skills/a2ui-remediate-problem/SKILL.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/a2ui-remediate-problem/SKILL.md","title":"a2ui-remediate-problem","category":"anthropic-skill","format":"markdown","content":"---\nname: a2ui-remediate-problem\ndescription: Remediates a specific recommendation from an A2UI compliance report issue, or resolves any general GitHub issue, by inspecting context, implementing minimal targeted fixes, verifying tests, creating a branch, and opening a developer-signed Pull Request. Use when asked to fix or remediate an A2UI compliance audit finding, recommendation, or repository issue.\n---\n\n# A2UI Issue & Compliance Remediation Skill\n\nThis skill guides an AI coding agent or engineer on how to remediate a specific recommendation from an A2UI compliance report or resolve any general repository issue and submit a clean, developer-signed Pull Request.\n\n---\n\n## **Workflow**\n\nFollow these steps to remediate an issue:\n\n### Step 1: Identify & Read Issue Context\n\n1. **Determine the Target Issue**:\n - If the user provided an issue number or URL in their request, extract `ISSUE_NUMBER`.\n - If no issue was specified, ask the user (prefer using the `ask_question` tool):\n _\"Which GitHub issue would you like to remediate? (Please provide the issue number or URL, e.g. 2391)\"_\n\n2. **Retrieve Context & Determine Issue Type**:\n - Run the helper script to inspect the issue:\n ```bash\n python3 .agents/skills/a2ui-remediate-problem/scripts/extract_recommendation.py \"${ISSUE_NUMBER}\" [RECOMMENDATION_INDEX] --json\n ```\n - **Scenario A: Compliance Report with Multiple Recommendations**:\n - If a recommendation index was provided (e.g. `2`), the script extracts that item's details and priority.\n - If no recommendation index was specified, the script outputs all available recommendations in the issue. Ask the user (via `ask_question`) which recommendation item they would like to address.\n - Review the surrounding audit sections in the report (such as `## Codebase Blueprint Compliance Audit`, `## Code & Documentation Sync Audit`, or `## Test Quality & Assertions Audit`) for detailed findings.\n - **Scenario B: General Issue (Bug Report, Feature Request, or Non-Audit Issue)**:\n - If the issue is not a compliance report, the script returns the issue title and body as the problem statement to remediate.\n\n---\n\n### Step 2: Formulate & Apply Remediation\n\n1. Identify the files and codebases referenced by the issue or recommendation.\n2. Carefully inspect the current source code, documentation, or blueprint files.\n3. Implement the minimal necessary change to remediate the reported problem.\n - **CRITICAL RULE**: Do not make unrelated changes, refactorings, or formatting edits outside the scope of the target issue or recommendation.\n4. Format modified files and ensure code style compliance:\n ```bash\n ./scripts/fix_format.sh\n ```\n5. If modifying tests or scripts, execute local tests across the affected packages to ensure no regressions were introduced.\n\n---\n\n### Step 3: Choose Destination & Create Workspace / Branch\n\n1. Check with the user on where they would like the changes created and what branch name to use (prefer using the `ask_question` tool or equivalent interactive tool if available):\n - **Recommended branch name**: `remediation/issue-${ISSUE_NUMBER}-${RECOMMENDATION_INDEX}` (or `remediation/issue-${ISSUE_NUMBER}` for general issues).\n - Let the user choose whether to create a separate git worktree (using their preferred local worktree conventions), checkout a new branch in the current directory, or apply changes in place.\n2. Note the chosen branch name in `BRANCH_NAME`.\n3. Ensure the working tree is clean and up to date with `upstream/main`.\n\n---\n\n### Step 4: Commit Changes\n\n1. Stage all modified files relevant to the remediation:\n ```bash\n git add -u\n ```\n2. Create a conventional commit referencing the issue number:\n - For compliance recommendations:\n ```bash\n git commit -m \"fix(compliance): remediate issue #${ISSUE_NUMBER} recommendation ${RECOMMENDATION_INDEX}\"\n ```\n - For general issues:\n ```bash\n git commit -m \"fix(scope): remediate issue #${ISSUE_NUMBER} - ${CONCISE_SUMMARY}\"\n ```\n\n---\n\n### Step 5: Create Pull Request & Notify Issue (Optional / Upon Request)\n\n1. Check with the user whether they would like to submit a Pull Request (prefer using the `ask_question` tool or equivalent interactive tool if available):\n - **Recommended default**: Submit as a Draft PR (`--draft`) so CI checks run while allowing final review before requesting maintainer approvals.\n - Alternatively, submit directly as ready for review, or skip PR creation if the user wants to inspect changes locally first.\n2. If submitting a PR, generate a clear, descriptive PR title following Conventional Commits that concisely explains the specific fix being made (e.g. `fix(swift): create missing top-level README in swift/core`). **Do NOT include generic issue or recommendation numbers in the PR title.**\n3. Draft the PR description into a temporary file `pr_description.md` following [pr-description-template.md](references/pr-description-template.md).\n4. Push the branch to `origin` (or user's fork) and create the Pull Request against `main`:\n ```bash\n git push -u origin \"${BRANCH_NAME}\"\n PR_URL=$(gh pr create --draft \\\n --repo a2ui-project/a2ui \\\n --head \"${BRANCH_NAME}\" \\\n --base main \\\n --title \"${PR_TITLE}\" \\\n --body-file pr_description.md)\n ```\n _(Note: Omit `--draft` if the user prefers an immediate ready-for-review PR. If pushing from a fork, `gh pr create` automatically resolves the fork's head branch or accepts `--head :${BRANCH_NAME}`.)_\n5. Clean up the temporary file `pr_description.md`.\n6. Comment on the original issue to notify maintainers of the new PR:\n ```bash\n gh issue comment \"${ISSUE_NUMBER}\" \\\n --repo a2ui-project/a2ui \\\n --body \"🤖 Automated remediation triggered! Created PR (${PR_URL}) on branch \\`${BRANCH_NAME}\\` to address recommendation ${RECOMMENDATION_INDEX}.\"\n ```\n\n---\n\n## **References**\n\n- Refer to the [PR description template](references/pr-description-template.md) for PR body structure and guidelines.\n- Refer to the [`gh-reference`](../a2ui-audit/references/gh-reference.md) for GitHub CLI commands.\n","frontmatter":{"name":"a2ui-remediate-problem","description":"Remediates a specific recommendation from an A2UI compliance report issue, or resolves any general GitHub issue, by inspecting context, implementing minimal targeted fixes, verifying tests, creating a branch, and opening a developer-signed Pull Request. Use when asked to fix or remediate an A2UI compliance audit finding, recommendation, or repository issue."},"isInternal":false,"tokens":1379,"sizeBytes":6137},{"name":"SKILL.md","path":".agents/skills/a2ui-test-quality-check/SKILL.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/a2ui-test-quality-check/SKILL.md","title":"a2ui-test-quality-check","category":"anthropic-skill","format":"markdown","content":"---\nname: a2ui-test-quality-check\ndescription: Auditing test suites for assertion utility, boundary cases coverage, and verification strength.\n---\n\n# A2UI Test Quality & Assertions Auditing Skill\n\nThis skill guides you through the process of auditing codebase test suites to verify that tests are providing robust, meaningful assertions and verifying critical invariants, rather than simply running paths for code coverage.\n\n---\n\n## **Instructions**\n\n1. **Locate Test Suites**:\n - Find all test directories and test files in each platform's implementation folder (e.g. `tests/`, `test/`, `*Tests.swift`).\n\n2. **Audit Assertion Quality**:\n - For each test case, inspect the assertions used:\n - Flag \"weak assertions\" that only verify non-null or truthy values without checking specific payload structure, field values, or types (e.g. `expect(result).not.toBeNull()` on a complex object).\n - Flag \"empty tests\" that execute code blocks but lack any assertions or mocks verifications (e.g. executing to check for lack of exceptions, unless it is explicitly marked as a no-throw smoke test).\n - Ensure that return models, state side effects, and events dispatched have corresponding value-matching assertions.\n\n3. **Audit Behavioral and Boundary Coverage**:\n - Review if tests exist for typical logical edge cases:\n - Null, empty, or overflow values.\n - Invalid JSON or parsing errors (e.g., throwing correct exceptions).\n - Exception propagation and error boundaries.\n - Timeout handling and cleanup side effects.\n - Look for cases where tests might pass when they should fail.\n - Cross-reference with the codebase's main files: if a file has complex parsing/validation code, ensure there are dedicated failing test cases asserting that errors are reported correctly.\n\n4. **Audit Mocking Realism**:\n - Ensure mocks and stubs verify their call parameters (e.g., verifying that a mock transport received the exact payload sent by the SDK, rather than just asserting it was called).\n\n5. **Format the Report**:\n - Build a Markdown report summarizing the findings:\n - Table of audited test suites and files.\n - **Weak Assertions**: List of test cases that rely on weak or missing assertions.\n - **Missing Edge Case Tests**: Critical logic boundaries and exception paths lacking tests.\n - **Mocking Mismatches**: Mock implementations that fail to verify call structures.\n - Return this Markdown report as your final response.\n","frontmatter":{"name":"a2ui-test-quality-check","description":"Auditing test suites for assertion utility, boundary cases coverage, and verification strength."},"isInternal":false,"tokens":509,"sizeBytes":2477},{"name":"SKILL.md","path":".agents/skills/coding-principles/SKILL.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/SKILL.md","title":"coding-principles","category":"anthropic-skill","format":"markdown","content":"---\nname: coding-principles\ndescription: >-\n Enforces engineering, architecture, public API, and code quality standards distilled from human\n reviewer feedback across A2UI pull requests. Use when authoring new code, refactoring, addressing\n review feedback, or reviewing PR diffs. Don't use for release publishing or spec blueprint\n generation without code or PR changes.\n---\n\n# Skill: coding-principles\n\n**Purpose**: Core engineering, architecture, and code quality standards established by human reviewers across A2UI pull requests. Used by agents when authoring changes, refactoring code, addressing review feedback, or reviewing pull request diffs to maintain repository health across all languages.\n\n---\n\n## Specification and Blueprint Grounding\n\nBefore modifying or implementing code in any language, consult the authoritative specifications and blueprints:\n\n- **Protocol JSON Schemas**: [`specification/v0_9_1/json/`](../../../specification/v0_9_1/json/) and [`specification/v1_0/json/`](../../../specification/v1_0/json/) define wire-format envelopes, types, and validation constraints.\n- **Component Catalogs**: [`catalogs/basic/v1/catalog.json`](../../../catalogs/basic/v1/catalog.json) defines standard components, properties, and function signatures.\n- **Core Module Blueprint**: [`a2ui_core.blueprint.md`](../../../blueprints/modules/a2ui_core.blueprint.md) specifies state containers (`DataModel`, `SurfaceModel`), `MessageProcessor`, JSON pointer rules, auto-vivification, and error semantics.\n- **Agent SDK Blueprint**: [`a2ui_agent.blueprint.md`](../../../blueprints/modules/a2ui_agent.blueprint.md) specifies `A2uiGenerator`, `A2uiRequestProcessor`, inference format strategies, and prompt generation.\n- **Framework Adapter Blueprint**: [`a2ui_framework_adapter.blueprint.md`](../../../blueprints/modules/a2ui_framework_adapter.blueprint.md) specifies view mapping, reactive subscription lifecycles, and layout behavior.\n- **Typesafe Builder Blueprint**: [`typesafe_builder_api.blueprint.md`](../../../blueprints/features/typesafe_builder_api.blueprint.md) specifies fluent builder hierarchies.\n- **Reference Implementation**: [`typescript/core/web_core/`](../../../typescript/core/web_core/) serves as the canonical behavioral reference for edge-case resolution.\n\n---\n\n## Progressive Discoverability: Two-Level Subskill Routing\n\nBecause the A2UI repository spans multiple languages (`typescript/`, `python/`, `dart/`, `swift/`) and shared specifications (`specification/`, `catalogs/`), agents must use a two-level progressive discovery workflow:\n\n1. **Level 1 (Cross-Language Subskills)**: Activate language-agnostic principles that govern pull request scope, software design, public API boundaries, specification immutability, and changelogs across the entire monorepo.\n2. **Level 2 (Language-Specific Routing)**: Route by the programming languages modified in the diff to load only the subskills and language guides relevant to those languages.\n\n### Step 1: Inspect the PR Diff\n\nReview the modified files and categories of changes:\n\n```bash\n# In an active branch:\ngit diff main --stat\n```\n\nIdentify both:\n\n- **Cross-cutting functional areas** impacted (public exports, specifications, catalogs, changelogs, PR structure).\n- **Programming languages and directories** touched (`typescript/`, `python/`, `dart/`, `swift/`, `samples/`, `tools/`).\n\n---\n\n### Step 2: Activate Cross-Language Subskills (Language-Agnostic)\n\nEvaluate the cross-language subskills below against the diff and read any activated document in full:\n\n#### 1. PR Hygiene, Atomicity, Scope Control & Software Design\n\n- **Skill**: [`pr-hygiene`](../pr-hygiene/SKILL.md)\n- **Activate if**: Always applicable when authoring, preparing, or reviewing a pull request.\n\n#### 2. Public API Boundaries, Cross-Framework Design & Changelogs\n\n- **Document**: [`subskills/public-api-and-cross-framework-design.md`](subskills/public-api-and-cross-framework-design.md)\n- **Activate if**:\n - Any package entrypoint or facade (`index.ts`, `public-api.ts`, `package.json`, `__init__.py`, `lib/*.dart`, or public Swift API), or any `CHANGELOG.md` is modified.\n - Any new class, function, interface, type, model, or DI token is exported.\n - Renderer APIs, registration helpers, or adapters across `@a2ui/angular`, `@a2ui/lit`, `@a2ui/react`, `a2ui_flutter`, or `A2UISwiftUI` are modified.\n - Imports between sibling packages change.\n - Files under `specification/` or `catalogs/` (schemas, catalog fixtures, or examples) are modified or added.\n - Breaking changes or public API deprecations are introduced.\n - A new source file is added (verify it has a single responsibility rather than acting as a catch-all `types.*` or `utils.*` file).\n\n#### 3. Updating Changelogs (`CHANGELOG.md`)\n\n- **Skill**: [`update-changelog`](../update-changelog/SKILL.md)\n- **Activate if**: Any `CHANGELOG.md` is modified or a published package's public API or consumer-observable behavior changes.\n\n---\n\n### Step 3: Route by Language for Language-Dependent Principles\n\nInspect the file extensions and directories in `git diff main --stat` and follow the matching language route(s) below. Only load routers and guides for languages present in your diff:\n\n| Language / Ecosystem | Matching Paths & Extensions | Progressive Discovery Target |\n| :-------------------------------------------------------------- | :--------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **TypeScript & Web** (Lit, Angular, React, Web Core, CSS, HTML) | `*.ts`, `*.tsx`, `*.css`, `typescript/`, `samples/client/{lit,angular,react}/`, `tools/` | Read the TypeScript & Web router: [`subskills/typescript/INDEX.md`](subskills/typescript/INDEX.md) to activate specific TypeScript, reactive lifecycle, CSS theming, accessibility, DOM testing, and AST public API subskills. |\n| **Python** (Core, Agent SDK, Builders, Evaluators, Scripts) | `*.py`, `python/`, `eval/`, `samples/agent/`, `tools/`, `scripts/` | Read the Python router: [`subskills/python/INDEX.md`](subskills/python/INDEX.md) to activate Python package architecture, facade conventions, typing, and verification subskills. |\n| **Swift & SwiftUI** (Core, SwiftUI Adapter, iOS Sample) | `*.swift`, `swift/`, `Package.swift` | Read the Swift & SwiftUI router: [`subskills/swift/INDEX.md`](subskills/swift/INDEX.md) to activate Swift target architecture, coding standards, and `Testing` subskills. |\n| **Dart & Flutter** (Core, Agent SDK, Flutter Adapter) | `*.dart`, `dart/`, `samples/client/flutter/`, `pubspec.yaml` | Read the Dart & Flutter router: [`subskills/dart/INDEX.md`](subskills/dart/INDEX.md) to activate Dart analyzer rules, package versioning, and changelog subskills. |\n\n---\n\n### Step 4: Progressively Load Activated Subskills\n\nRead only the cross-language subskills activated in Step 2 and the language-specific subskills selected through Step 3 to evaluate your code against their rationales, checklists, and examples without loading unrelated language rules into context.\n","frontmatter":{"name":"coding-principles","description":"Enforces engineering, architecture, public API, and code quality standards distilled from human reviewer feedback across A2UI pull requests. Use when authoring new code, refactoring, addressing review feedback, or reviewing PR diffs. Don't use for release publishing or spec blueprint generation without code or PR changes."},"isInternal":false,"tokens":1602,"sizeBytes":7822},{"name":"INDEX.md","path":".agents/skills/coding-principles/subskills/dart/INDEX.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/dart/INDEX.md","title":"Dart Skill","category":"anthropic-skill","format":"markdown","content":"# Dart Skill\n\nPath: `.agents/skills/coding-principles/subskills/dart/INDEX.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/dart/INDEX.md)","tokens":300,"sizeBytes":223},{"name":"versioning-and-releases.md","path":".agents/skills/coding-principles/subskills/dart/versioning-and-releases.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/dart/versioning-and-releases.md","title":"Dart Skill","category":"anthropic-skill","format":"markdown","content":"# Dart Skill\n\nPath: `.agents/skills/coding-principles/subskills/dart/versioning-and-releases.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/dart/versioning-and-releases.md)","tokens":300,"sizeBytes":259},{"name":"public-api-and-cross-framework-design.md","path":".agents/skills/coding-principles/subskills/public-api-and-cross-framework-design.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/public-api-and-cross-framework-design.md","title":"Subskills Skill","category":"anthropic-skill","format":"markdown","content":"# Subskills Skill\n\nPath: `.agents/skills/coding-principles/subskills/public-api-and-cross-framework-design.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/public-api-and-cross-framework-design.md)","tokens":300,"sizeBytes":282},{"name":"architecture-and-facades.md","path":".agents/skills/coding-principles/subskills/python/architecture-and-facades.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/python/architecture-and-facades.md","title":"Python Skill","category":"anthropic-skill","format":"markdown","content":"# Python Skill\n\nPath: `.agents/skills/coding-principles/subskills/python/architecture-and-facades.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/python/architecture-and-facades.md)","tokens":300,"sizeBytes":267},{"name":"coding-standards-and-verification.md","path":".agents/skills/coding-principles/subskills/python/coding-standards-and-verification.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/python/coding-standards-and-verification.md","title":"Python Skill","category":"anthropic-skill","format":"markdown","content":"# Python Skill\n\nPath: `.agents/skills/coding-principles/subskills/python/coding-standards-and-verification.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/python/coding-standards-and-verification.md)","tokens":300,"sizeBytes":285},{"name":"INDEX.md","path":".agents/skills/coding-principles/subskills/python/INDEX.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/python/INDEX.md","title":"Python Skill","category":"anthropic-skill","format":"markdown","content":"# Python Skill\n\nPath: `.agents/skills/coding-principles/subskills/python/INDEX.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/python/INDEX.md)","tokens":300,"sizeBytes":229},{"name":"coding-standards-and-testing.md","path":".agents/skills/coding-principles/subskills/swift/coding-standards-and-testing.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/swift/coding-standards-and-testing.md","title":"Swift Skill","category":"anthropic-skill","format":"markdown","content":"# Swift Skill\n\nPath: `.agents/skills/coding-principles/subskills/swift/coding-standards-and-testing.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/swift/coding-standards-and-testing.md)","tokens":300,"sizeBytes":272},{"name":"INDEX.md","path":".agents/skills/coding-principles/subskills/swift/INDEX.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/swift/INDEX.md","title":"Swift Skill","category":"anthropic-skill","format":"markdown","content":"# Swift Skill\n\nPath: `.agents/skills/coding-principles/subskills/swift/INDEX.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/swift/INDEX.md)","tokens":300,"sizeBytes":226},{"name":"accessibility-semantics.md","path":".agents/skills/coding-principles/subskills/typescript/accessibility-semantics.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/accessibility-semantics.md","title":"Typescript Skill","category":"anthropic-skill","format":"markdown","content":"# Typescript Skill\n\nPath: `.agents/skills/coding-principles/subskills/typescript/accessibility-semantics.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/accessibility-semantics.md)","tokens":300,"sizeBytes":277},{"name":"css-theming-styling.md","path":".agents/skills/coding-principles/subskills/typescript/css-theming-styling.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/css-theming-styling.md","title":"Typescript Skill","category":"anthropic-skill","format":"markdown","content":"# Typescript Skill\n\nPath: `.agents/skills/coding-principles/subskills/typescript/css-theming-styling.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/css-theming-styling.md)","tokens":300,"sizeBytes":269},{"name":"INDEX.md","path":".agents/skills/coding-principles/subskills/typescript/INDEX.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/INDEX.md","title":"Typescript Skill","category":"anthropic-skill","format":"markdown","content":"# Typescript Skill\n\nPath: `.agents/skills/coding-principles/subskills/typescript/INDEX.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/INDEX.md)","tokens":300,"sizeBytes":241},{"name":"reactive-lifecycle-performance.md","path":".agents/skills/coding-principles/subskills/typescript/reactive-lifecycle-performance.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/reactive-lifecycle-performance.md","title":"Typescript Skill","category":"anthropic-skill","format":"markdown","content":"# Typescript Skill\n\nPath: `.agents/skills/coding-principles/subskills/typescript/reactive-lifecycle-performance.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/reactive-lifecycle-performance.md)","tokens":300,"sizeBytes":291},{"name":"inspecting-typescript-public-api.md","path":".agents/skills/coding-principles/subskills/typescript/references/inspecting-typescript-public-api.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/references/inspecting-typescript-public-api.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# References Skill\n\nPath: `.agents/skills/coding-principles/subskills/typescript/references/inspecting-typescript-public-api.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/references/inspecting-typescript-public-api.md)","tokens":300,"sizeBytes":317},{"name":"testing-isolation.md","path":".agents/skills/coding-principles/subskills/typescript/testing-isolation.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/testing-isolation.md","title":"Typescript Skill","category":"anthropic-skill","format":"markdown","content":"# Typescript Skill\n\nPath: `.agents/skills/coding-principles/subskills/typescript/testing-isolation.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/testing-isolation.md)","tokens":300,"sizeBytes":265},{"name":"typescript-closure-compiler.md","path":".agents/skills/coding-principles/subskills/typescript/typescript-closure-compiler.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/typescript-closure-compiler.md","title":"Typescript Skill","category":"anthropic-skill","format":"markdown","content":"# Typescript Skill\n\nPath: `.agents/skills/coding-principles/subskills/typescript/typescript-closure-compiler.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/typescript-closure-compiler.md)","tokens":300,"sizeBytes":285},{"name":"SKILL.md","path":".agents/skills/inspect-ai/SKILL.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/inspect-ai/SKILL.md","title":"inspect-ai","category":"anthropic-skill","format":"markdown","content":"---\nname: inspect-ai\ndescription: Useful when working with the Inspect AI evaluation framework (e.g., in the eval/ directory). Provides instructions on how to access Inspect AI documentation.\n---\n\n# Inspect AI Framework Guidelines\n\nWhen you are tasked with creating, modifying, or debugging evaluation scripts (especially within the `eval/` directory) that utilize the **Inspect AI** framework, you should consult the official documentation to ensure you are using the correct APIs, solvers, scorers, and best practices.\n\n### Documentation Source\n\nTo learn how to use Inspect AI, read the official LLM-optimized documentation guide by fetching the following URL using your `read_url_content` tool:\n\n`https://inspect.aisi.org.uk/llms.txt`\n\nAlways reference this document when you need clarification on how Inspect AI handles task execution, scoring objects, parallelism, or tool calling architectures.\n","frontmatter":{"name":"inspect-ai","description":"Useful when working with the Inspect AI evaluation framework (e.g., in the eval/ directory). Provides instructions on how to access Inspect AI documentation."},"isInternal":false,"tokens":183,"sizeBytes":901},{"name":"SKILL.md","path":".agents/skills/natural-writing/SKILL.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/natural-writing/SKILL.md","title":"natural-writing","category":"anthropic-skill","format":"markdown","content":"---\nname: natural-writing\ndescription: Contains well-defined rules for creating natural, accurate, and readable writing. Use this skill whenever authoring longer text, including reports, PR descriptions, READMEs, system designs, analysis documents, or general documentation.\n---\n\n# Rules for natural writing\n\nThis document outlines strict rules to avoid common \"AI-isms\": stylistic and structural patterns that language models typically fall into. Follow these rules to produce content that is more understandable, and reads as natural, human-authored text.\n\nThe rules are numbered so that reviews can cite them, as in \"rule 3.2\".\n\n## 1. Vocabulary & phrasing controls\n\n### 1.1. The \"banned\" list\n\nAvoid words that are statistically overrepresented in AI text. Use simpler, more direct alternatives.\n\nAvoid verbs that are commonly overused, such as delve, underscore, highlight (as a verb), foster, cultivate, maximize, leverage, democratize, ensure, align with, resonate with, encompass, and bridge. Also avoid adverbs like seamlessly and extensively.\n\nFor nouns, avoid abstract uses of tapestry, landscape, realm, testament, interplay, synergy, cornerstone, hub, and ecosystem.\n\nFor adjectives, avoid puffery and vague descriptors like pivotal, crucial, vibrant, intricate, nuanced, unwavering, indelible, uncharted, rapidly evolving, transformative, breathtaking, nestled, dynamic, comprehensive, intuitive, holistic, robust, frictionless, scalable, and synergistic.\n\n### 1.2. Avoid \"copula\" substitutions\n\nDo not replace simple \"is\" or \"are\" verbs with flowery equivalents.\n\n- Instead of: \"The library _serves as_ a center for learning.\"\n- Write: \"The library _is_ a center for learning.\"\n- Instead of: \"The statue _stands as_ a monument to...\"\n- Write: \"The statue _is_ a monument to...\"\n\n### 1.3. Eliminate \"elegant variation\"\n\nDo not use synonyms just to avoid repeating a subject's name (e.g., \"the eponymous character,\" \"the titular protagonist,\" \"the celebrated author\"). It is acceptable to repeat the name or use pronouns naturally.\n\n### 1.4. Prefer literal words to idioms\n\nChoose the word that states the meaning directly over an idiom whose meaning depends on context. Idioms are harder to read for non-native speakers and for anyone skimming instructions.\n\n- Instead of: \"Leave the version _alone_.\"\n- Write: \"Leave the version _untouched_.\"\n\n### 1.5. Name things in full for a reader without your context\n\nUse the full name of a term when first mentioning it. Shorthand that was clear during development—such as an informal name for a part of the codebase may be meaningless to reviewers and future readers who lack that context.\n\n- Instead of: \"The suites are read through `_plain`.\"\n- Write: \"The conformance suites (the YAML test cases under `conformance/`) are read through `_plain`.\"\n\n## 2. Content & tone\n\n### 2.1. No \"puffery\" or forced significance\n\nDo not inflate the importance of a topic with vague praise. If a subject is important, the facts should demonstrate it without help.\n\nAvoid phrases like \"serves as a testament to,\" \"marking a pivotal moment,\" \"underscoring the importance of,\" \"leaving an indelible mark,\" or \"shaping the landscape.\"\n\n- Instead of: \"The founding of the institute marked a pivotal moment in the evolution of regional statistics, representing a significant shift toward independence.\"\n- Write: \"The institute was founded in 1989 to collect regional statistics.\"\n\n### 2.2. No superficial analysis\n\nAvoid attaching \"dangling\" present-participle phrases that offer vague commentary.\n\nDelete clauses starting with \"highlighting,\" \"emphasizing,\" \"reflecting,\" \"showcasing,\" or \"demonstrating\" if they just restate the obvious or add fluff.\n\n- Instead of: \"The building uses blue glass, _reflecting the region's natural beauty and symbolizing unity._\"\n- Write: \"The building uses blue glass.\"\n\n### 2.3. Avoid promotional language\n\nMaintain a neutral tone. Avoid \"advertisement\" words like boasts, features (as a verb), offers, premier, leading, state-of-the-art, committed to, and dedicated to.\n\n- Instead of: \"Nestled in the heart of the city, the hotel boasts a vibrant atmosphere.\"\n- Write: \"The hotel is located in the city center.\"\n\n### 2.4. No \"challenges and future outlook\" formula\n\nLanguage models often end articles with a generic \"Despite challenges... remains important\" conclusion. Do not end with a summary paragraph starting with \"Despite [X], [Subject] continues to...\" or speculating on the future. End with the last fact.\n\n- Bad: \"Despite facing economic hurdles, the company continues to thrive and remains a beacon of innovation.\"\n\n### 2.5. No \"title as proper noun\" leads\n\nDo not treat a descriptive article title (like a list or broad topic) as a proper noun in the first sentence.\n\n- Instead of: \"_The List of songs about Mexico_ is a curated compilation...\"\n- Write: \"This list contains songs about Mexico...\"\n\n### 2.6. No generic \"see also\" links\n\nDo not populate \"See Also\" sections with broad, generic terms. Links must be directly relevant and specific to the subject.\n\n- Bad: Linking _Financial technology_ in an article about a specific startup.\n- Good: Linking a competitor or specific related technology.\n\n### 2.7. Attribution precision\n\nAvoid vague \"weasel words\" like \"Experts argue,\" \"Observers have noted,\" or \"Several sources indicate\" unless you cite specific people immediately. Do not claim a subject interacts with a \"broader\" history or trend unless a source explicitly says so.\n\n## 3. Sentence structure\n\n### 3.1. No negative parallelism\n\nAvoid sentences that structure a contrast unnecessarily.\n\n- Instead of: \"It is _not only_ a painting, _but also_ a representation of...\"\n- Instead of: \"It is _not_ just about X; _it is_ about Y.\"\n- Write: \"It is a painting that represents...\"\n\n### 3.2. No \"rule of three\"\n\nAvoid listing exactly three adjectives or three noun phrases to sound \"comprehensive.\"\n\n- Bad: \"The event brings together _marketers, engineers, and designers_.\" (Unless those specific three groups are the _only_ ones).\n- Bad: \"It is _bold, innovative, and unique_.\"\n\n### 3.3. No false ranges\n\nDo not use \"from X to Y\" unless X and Y are endpoints of a logical scale (like time or size).\n\n- Instead of: \"The book covers everything _from_ biology _to_ space travel.\" (These are just two random topics, not a range).\n- Write: \"The book covers topics including biology and space travel.\"\n\n## 4. Structure & formatting\n\n### 4.1. Headers\n\nUse sentence case for headers (e.g., \"Early life,\" not \"Early Life\"). Do not use title case in headers.\n\n### 4.2. Formatting avoidance\n\nDo not use inline-header lists (such as `* **Header:** Description...`). Instead, use prose or simple lists.\n\nAvoid excessive bolding of keywords, \"key takeaways,\" or names in the body text, except for the first mention in the lead.\n\nUse numbered lists (`1.`, `2.`) instead of bullets, so readers can refer to an item by its number, as in \"see point 3\" (except in changelogs, which use `-` bullets; see [`update-changelog`](../update-changelog/SKILL.md)). Do not use emojis (🚀, 🧠) as list markers.\n\nAvoid creating tables for simple information that easily fits in a sentence.\n\nEnsure markup is context-appropriate; do not use Markdown (like `##`) in formats that do not support it (like Wikitext) unless it is explicitly converted.\n\n### 4.3. Punctuation\n\nUse straight quotes (`\"`, `'`) and straight apostrophes (`'`). Do not use curly or smart quotes (`“`, `’`).\n\nUse em dashes sparingly, as language models often overuse them for emphasis. Prefer commas or parentheses instead.\n\n## 5. Citations & integrity\n\n### 5.1. No hallucinations\n\nNever generate a citation unless you are looking at the source.\nDo not invent URLs or DOIs.\nDo not assume a book exists or contains a specific fact without verification.\n\n### 5.2. Link what you mention\n\nLink everything the reader may want to open: files, functions, test and conformance cases, packages, issues, pull requests, and external pages. How precise a link should be depends on how long the text lives.\n\n1. In short-lived text, such as review comments, PR descriptions, and issues, link to the exact lines. Pin the link to a commit SHA rather than a branch, so it keeps pointing at the lines you meant after the branch moves. For a Markdown file, add `?plain=1` so a line anchor such as `#L10-L20` works.\n2. In long-lived documents, such as READMEs, documentation, skills, and code comments, link to the file or its section, without line ranges. A line range in one long-lived document has to be updated every time the document it points to changes.\n3. Link only to what the reader can see at the link target. If your change is not pushed yet, link to the current version, or post the text after the push.\n4. Before posting, check that every link resolves.\n\n## 6. Communication (chat context)\n\nAvoid collaborative filler at the start of responses, such as \"Certainly!\", \"Here is the information,\" or \"I hope this helps.\" State the content directly.\n\nDo not apologize for being an AI or mention knowledge cutoffs unless it is relevant to a specific, time-sensitive fact.\n\nDo not preface responses with subject lines.\n\nKeep edit summaries concise and informal, avoiding verbose paragraphs.\n","frontmatter":{"name":"natural-writing","description":"Contains well-defined rules for creating natural, accurate, and readable writing. Use this skill whenever authoring longer text, including reports, PR descriptions, READMEs, system designs, analysis documents, or general documentation."},"isInternal":false,"tokens":2128,"sizeBytes":9221},{"name":"SKILL.md","path":".agents/skills/pr-hygiene/SKILL.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/pr-hygiene/SKILL.md","title":"pr-hygiene","category":"anthropic-skill","format":"markdown","content":"# pr-hygiene\n\nPath: `.agents/skills/pr-hygiene/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/pr-hygiene/SKILL.md)","tokens":300,"sizeBytes":179},{"name":"SKILL.md","path":".agents/skills/update-changelog/SKILL.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/update-changelog/SKILL.md","title":"update-changelog","category":"anthropic-skill","format":"markdown","content":"# update-changelog\n\nPath: `.agents/skills/update-changelog/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/update-changelog/SKILL.md)","tokens":300,"sizeBytes":197},{"name":"SKILL.md","path":"blueprints/skills/a2ui-blueprint-compliance/SKILL.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/blueprints/skills/a2ui-blueprint-compliance/SKILL.md","title":"a2ui-blueprint-compliance","category":"anthropic-skill","format":"markdown","content":"# a2ui-blueprint-compliance\n\nPath: `blueprints/skills/a2ui-blueprint-compliance/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/blueprints/skills/a2ui-blueprint-compliance/SKILL.md)","tokens":300,"sizeBytes":230},{"name":"SKILL.md","path":"blueprints/skills/a2ui-blueprint-maintenance/SKILL.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/blueprints/skills/a2ui-blueprint-maintenance/SKILL.md","title":"a2ui-blueprint-maintenance","category":"anthropic-skill","format":"markdown","content":"# a2ui-blueprint-maintenance\n\nPath: `blueprints/skills/a2ui-blueprint-maintenance/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/blueprints/skills/a2ui-blueprint-maintenance/SKILL.md)","tokens":300,"sizeBytes":233},{"name":"SKILL.md","path":"blueprints/skills/a2ui-blueprint-navigator/SKILL.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/blueprints/skills/a2ui-blueprint-navigator/SKILL.md","title":"a2ui-blueprint-navigator","category":"anthropic-skill","format":"markdown","content":"# a2ui-blueprint-navigator\n\nPath: `blueprints/skills/a2ui-blueprint-navigator/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/blueprints/skills/a2ui-blueprint-navigator/SKILL.md)","tokens":300,"sizeBytes":227},{"name":"SKILL.md","path":"blueprints/skills/a2ui-create-feature-blueprint/SKILL.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/blueprints/skills/a2ui-create-feature-blueprint/SKILL.md","title":"a2ui-create-feature-blueprint","category":"anthropic-skill","format":"markdown","content":"# a2ui-create-feature-blueprint\n\nPath: `blueprints/skills/a2ui-create-feature-blueprint/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/blueprints/skills/a2ui-create-feature-blueprint/SKILL.md)","tokens":300,"sizeBytes":242},{"name":"SKILL.md","path":"blueprints/skills/a2ui-implement-feature-from-blueprint/SKILL.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/blueprints/skills/a2ui-implement-feature-from-blueprint/SKILL.md","title":"a2ui-implement-feature-from-blueprint","category":"anthropic-skill","format":"markdown","content":"# a2ui-implement-feature-from-blueprint\n\nPath: `blueprints/skills/a2ui-implement-feature-from-blueprint/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/blueprints/skills/a2ui-implement-feature-from-blueprint/SKILL.md)","tokens":300,"sizeBytes":266},{"name":"a2a_integration.yaml","path":"conformance/extensions/a2a/a2a_integration.yaml","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/conformance/extensions/a2a/a2a_integration.yaml","title":"A2a Skill","category":"anthropic-skill","format":"yaml","content":"# A2a Skill\n\nPath: `conformance/extensions/a2a/a2a_integration.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/conformance/extensions/a2a/a2a_integration.yaml)","tokens":300,"sizeBytes":204},{"name":"adk_extensions.yaml","path":"conformance/extensions/adk/adk_extensions.yaml","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/conformance/extensions/adk/adk_extensions.yaml","title":"Adk Skill","category":"anthropic-skill","format":"yaml","content":"# Adk Skill\n\nPath: `conformance/extensions/adk/adk_extensions.yaml`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/conformance/extensions/adk/adk_extensions.yaml)","tokens":300,"sizeBytes":202},{"name":"express_basic_catalog.skill.md","path":"conformance/test_data/skills/express_basic_catalog.skill.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/conformance/test_data/skills/express_basic_catalog.skill.md","title":"Skills Skill","category":"anthropic-skill","format":"markdown","content":"# Skills Skill\n\nPath: `conformance/test_data/skills/express_basic_catalog.skill.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/conformance/test_data/skills/express_basic_catalog.skill.md)","tokens":300,"sizeBytes":231},{"name":"express_basic_monolithic.skill.md","path":"conformance/test_data/skills/express_basic_monolithic.skill.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/conformance/test_data/skills/express_basic_monolithic.skill.md","title":"Skills Skill","category":"anthropic-skill","format":"markdown","content":"# Skills Skill\n\nPath: `conformance/test_data/skills/express_basic_monolithic.skill.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/conformance/test_data/skills/express_basic_monolithic.skill.md)","tokens":300,"sizeBytes":237},{"name":"express_core.skill.md","path":"conformance/test_data/skills/express_core.skill.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/conformance/test_data/skills/express_core.skill.md","title":"Skills Skill","category":"anthropic-skill","format":"markdown","content":"# Skills Skill\n\nPath: `conformance/test_data/skills/express_core.skill.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/conformance/test_data/skills/express_core.skill.md)","tokens":300,"sizeBytes":213},{"name":"fake_monolithic.skill.md","path":"conformance/test_data/skills/fake_monolithic.skill.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/conformance/test_data/skills/fake_monolithic.skill.md","title":"Skills Skill","category":"anthropic-skill","format":"markdown","content":"# Skills Skill\n\nPath: `conformance/test_data/skills/fake_monolithic.skill.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/conformance/test_data/skills/fake_monolithic.skill.md)","tokens":300,"sizeBytes":219},{"name":"agent_instructions.md","path":"eval/iterative_format_optimizer/skills/inference-format-optimizer/references/agent_instructions.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/iterative_format_optimizer/skills/inference-format-optimizer/references/agent_instructions.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# References Skill\n\nPath: `eval/iterative_format_optimizer/skills/inference-format-optimizer/references/agent_instructions.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/iterative_format_optimizer/skills/inference-format-optimizer/references/agent_instructions.md)","tokens":300,"sizeBytes":313},{"name":"inference_format_iteration.md","path":"eval/iterative_format_optimizer/skills/inference-format-optimizer/references/inference_format_iteration.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/iterative_format_optimizer/skills/inference-format-optimizer/references/inference_format_iteration.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# References Skill\n\nPath: `eval/iterative_format_optimizer/skills/inference-format-optimizer/references/inference_format_iteration.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/iterative_format_optimizer/skills/inference-format-optimizer/references/inference_format_iteration.md)","tokens":300,"sizeBytes":329},{"name":"scoring_model.md","path":"eval/iterative_format_optimizer/skills/inference-format-optimizer/references/scoring_model.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/iterative_format_optimizer/skills/inference-format-optimizer/references/scoring_model.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# References Skill\n\nPath: `eval/iterative_format_optimizer/skills/inference-format-optimizer/references/scoring_model.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/iterative_format_optimizer/skills/inference-format-optimizer/references/scoring_model.md)","tokens":300,"sizeBytes":303},{"name":"subagent_protocol.md","path":"eval/iterative_format_optimizer/skills/inference-format-optimizer/references/subagent_protocol.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/iterative_format_optimizer/skills/inference-format-optimizer/references/subagent_protocol.md","title":"References Skill","category":"anthropic-skill","format":"markdown","content":"# References Skill\n\nPath: `eval/iterative_format_optimizer/skills/inference-format-optimizer/references/subagent_protocol.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/iterative_format_optimizer/skills/inference-format-optimizer/references/subagent_protocol.md)","tokens":300,"sizeBytes":311},{"name":"README.md","path":"eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/README.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/README.md","title":"Scripts Skill","category":"anthropic-skill","format":"markdown","content":"# Scripts Skill\n\nPath: `eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/iterative_format_optimizer/skills/inference-format-optimizer/scripts/README.md)","tokens":300,"sizeBytes":280},{"name":"SKILL.md","path":"eval/iterative_format_optimizer/skills/inference-format-optimizer/SKILL.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/iterative_format_optimizer/skills/inference-format-optimizer/SKILL.md","title":"inference-format-optimizer","category":"anthropic-skill","format":"markdown","content":"# inference-format-optimizer\n\nPath: `eval/iterative_format_optimizer/skills/inference-format-optimizer/SKILL.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/iterative_format_optimizer/skills/inference-format-optimizer/SKILL.md)","tokens":300,"sizeBytes":275},{"name":"subagent_prompt.md","path":"eval/iterative_format_optimizer/skills/inference-format-optimizer/templates/subagent_prompt.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/iterative_format_optimizer/skills/inference-format-optimizer/templates/subagent_prompt.md","title":"Templates Skill","category":"anthropic-skill","format":"markdown","content":"# Templates Skill\n\nPath: `eval/iterative_format_optimizer/skills/inference-format-optimizer/templates/subagent_prompt.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/iterative_format_optimizer/skills/inference-format-optimizer/templates/subagent_prompt.md)","tokens":300,"sizeBytes":304},{"name":"a2ui_extension_specification.md","path":"specification/v1_0/extensions/a2a/docs/a2ui_extension_specification.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/specification/v1_0/extensions/a2a/docs/a2ui_extension_specification.md","title":"Docs Skill","category":"anthropic-skill","format":"markdown","content":"# Docs Skill\n\nPath: `specification/v1_0/extensions/a2a/docs/a2ui_extension_specification.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/specification/v1_0/extensions/a2a/docs/a2ui_extension_specification.md)","tokens":300,"sizeBytes":251},{"name":"basic_catalog.json","path":"tools/build_catalog/tests/fixtures/basic_catalog.json","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/tests/fixtures/basic_catalog.json","title":"Fixtures Skill","category":"anthropic-skill","format":"json","content":"# Fixtures Skill\n\nPath: `tools/build_catalog/tests/fixtures/basic_catalog.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/tests/fixtures/basic_catalog.json)","tokens":300,"sizeBytes":221},{"name":"common_types.json","path":"tools/build_catalog/tests/fixtures/common_types.json","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/tests/fixtures/common_types.json","title":"Fixtures Skill","category":"anthropic-skill","format":"json","content":"# Fixtures Skill\n\nPath: `tools/build_catalog/tests/fixtures/common_types.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/tests/fixtures/common_types.json)","tokens":300,"sizeBytes":219},{"name":"component1.json","path":"tools/build_catalog/tests/fixtures/component1.json","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/tests/fixtures/component1.json","title":"Fixtures Skill","category":"anthropic-skill","format":"json","content":"# Fixtures Skill\n\nPath: `tools/build_catalog/tests/fixtures/component1.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/tests/fixtures/component1.json)","tokens":300,"sizeBytes":215},{"name":"component2.json","path":"tools/build_catalog/tests/fixtures/component2.json","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/tests/fixtures/component2.json","title":"Fixtures Skill","category":"anthropic-skill","format":"json","content":"# Fixtures Skill\n\nPath: `tools/build_catalog/tests/fixtures/component2.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/tests/fixtures/component2.json)","tokens":300,"sizeBytes":215},{"name":"component3.json","path":"tools/build_catalog/tests/fixtures/component3.json","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/tests/fixtures/component3.json","title":"Fixtures Skill","category":"anthropic-skill","format":"json","content":"# Fixtures Skill\n\nPath: `tools/build_catalog/tests/fixtures/component3.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/tests/fixtures/component3.json)","tokens":300,"sizeBytes":215},{"name":"v0_8_custom_catalog.json","path":"tools/build_catalog/tests/fixtures/v0_8_custom_catalog.json","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/tests/fixtures/v0_8_custom_catalog.json","title":"Fixtures Skill","category":"anthropic-skill","format":"json","content":"# Fixtures Skill\n\nPath: `tools/build_catalog/tests/fixtures/v0_8_custom_catalog.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/tests/fixtures/v0_8_custom_catalog.json)","tokens":300,"sizeBytes":233},{"name":"v0_8_standard_catalog_definition.json","path":"tools/build_catalog/tests/fixtures/v0_8_standard_catalog_definition.json","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/tests/fixtures/v0_8_standard_catalog_definition.json","title":"Fixtures Skill","category":"anthropic-skill","format":"json","content":"# Fixtures Skill\n\nPath: `tools/build_catalog/tests/fixtures/v0_8_standard_catalog_definition.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/tests/fixtures/v0_8_standard_catalog_definition.json)","tokens":300,"sizeBytes":259},{"name":"AGENTS.md","path":"tools/composer/AGENTS.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/AGENTS.md","title":"Composer Skill","category":"anthropic-skill","format":"markdown","content":"# Composer Skill\n\nPath: `tools/composer/AGENTS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/AGENTS.md)","tokens":300,"sizeBytes":163},{"name":"components.json","path":"tools/composer/components.json","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/components.json","title":"Composer Skill","category":"anthropic-skill","format":"json","content":"# Composer Skill\n\nPath: `tools/composer/components.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/components.json)","tokens":300,"sizeBytes":175},{"name":"package.json","path":"tools/composer/package.json","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/package.json","title":"Composer Skill","category":"anthropic-skill","format":"json","content":"# Composer Skill\n\nPath: `tools/composer/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/package.json)","tokens":300,"sizeBytes":169},{"name":"booking-form.json","path":"tools/composer/src/data/theater/booking-form.json","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/booking-form.json","title":"Theater Skill","category":"anthropic-skill","format":"json","content":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/booking-form.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/booking-form.json)","tokens":300,"sizeBytes":212},{"name":"component-gallery-stream.json","path":"tools/composer/src/data/theater/component-gallery-stream.json","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/component-gallery-stream.json","title":"Theater Skill","category":"anthropic-skill","format":"json","content":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/component-gallery-stream.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/component-gallery-stream.json)","tokens":300,"sizeBytes":236},{"name":"contact-card.json","path":"tools/composer/src/data/theater/contact-card.json","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/contact-card.json","title":"Theater Skill","category":"anthropic-skill","format":"json","content":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/contact-card.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/contact-card.json)","tokens":300,"sizeBytes":212},{"name":"flight-status.json","path":"tools/composer/src/data/theater/flight-status.json","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/flight-status.json","title":"Theater Skill","category":"anthropic-skill","format":"json","content":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/flight-status.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/flight-status.json)","tokens":300,"sizeBytes":214},{"name":"floor-plan.json","path":"tools/composer/src/data/theater/floor-plan.json","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/floor-plan.json","title":"Theater Skill","category":"anthropic-skill","format":"json","content":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/floor-plan.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/floor-plan.json)","tokens":300,"sizeBytes":208},{"name":"kitchen-sink.json","path":"tools/composer/src/data/theater/kitchen-sink.json","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/kitchen-sink.json","title":"Theater Skill","category":"anthropic-skill","format":"json","content":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/kitchen-sink.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/kitchen-sink.json)","tokens":300,"sizeBytes":212},{"name":"northstar-tour.json","path":"tools/composer/src/data/theater/northstar-tour.json","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/northstar-tour.json","title":"Theater Skill","category":"anthropic-skill","format":"json","content":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/northstar-tour.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/northstar-tour.json)","tokens":300,"sizeBytes":216},{"name":"org-chart.json","path":"tools/composer/src/data/theater/org-chart.json","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/org-chart.json","title":"Theater Skill","category":"anthropic-skill","format":"json","content":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/org-chart.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/org-chart.json)","tokens":300,"sizeBytes":206},{"name":"restaurant-booking.json","path":"tools/composer/src/data/theater/restaurant-booking.json","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/restaurant-booking.json","title":"Theater Skill","category":"anthropic-skill","format":"json","content":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/restaurant-booking.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/restaurant-booking.json)","tokens":300,"sizeBytes":224},{"name":"restaurant-confirmation.json","path":"tools/composer/src/data/theater/restaurant-confirmation.json","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/restaurant-confirmation.json","title":"Theater Skill","category":"anthropic-skill","format":"json","content":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/restaurant-confirmation.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/restaurant-confirmation.json)","tokens":300,"sizeBytes":234},{"name":"restaurant-finder.json","path":"tools/composer/src/data/theater/restaurant-finder.json","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/restaurant-finder.json","title":"Theater Skill","category":"anthropic-skill","format":"json","content":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/restaurant-finder.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/restaurant-finder.json)","tokens":300,"sizeBytes":222},{"name":"restaurant-grid.json","path":"tools/composer/src/data/theater/restaurant-grid.json","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/restaurant-grid.json","title":"Theater Skill","category":"anthropic-skill","format":"json","content":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/restaurant-grid.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/restaurant-grid.json)","tokens":300,"sizeBytes":218},{"name":"rizzcharts-chart.json","path":"tools/composer/src/data/theater/rizzcharts-chart.json","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/rizzcharts-chart.json","title":"Theater Skill","category":"anthropic-skill","format":"json","content":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/rizzcharts-chart.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/rizzcharts-chart.json)","tokens":300,"sizeBytes":220},{"name":"weather-widget.json","path":"tools/composer/src/data/theater/weather-widget.json","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/weather-widget.json","title":"Theater Skill","category":"anthropic-skill","format":"json","content":"# Theater Skill\n\nPath: `tools/composer/src/data/theater/weather-widget.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/src/data/theater/weather-widget.json)","tokens":300,"sizeBytes":216},{"name":"tsconfig.json","path":"tools/composer/tsconfig.json","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/tsconfig.json","title":"Composer Skill","category":"anthropic-skill","format":"json","content":"# Composer Skill\n\nPath: `tools/composer/tsconfig.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/tsconfig.json)","tokens":300,"sizeBytes":171},{"name":"package.json","path":"tools/editor/package.json","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/editor/package.json","title":"Editor Skill","category":"anthropic-skill","format":"json","content":"# Editor Skill\n\nPath: `tools/editor/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/editor/package.json)","tokens":300,"sizeBytes":163},{"name":"tsconfig.json","path":"tools/editor/tsconfig.json","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/editor/tsconfig.json","title":"Editor Skill","category":"anthropic-skill","format":"json","content":"# Editor Skill\n\nPath: `tools/editor/tsconfig.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/editor/tsconfig.json)","tokens":300,"sizeBytes":165},{"name":"package.json","path":"tools/inspector/package.json","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/inspector/package.json","title":"Inspector Skill","category":"anthropic-skill","format":"json","content":"# Inspector Skill\n\nPath: `tools/inspector/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/inspector/package.json)","tokens":300,"sizeBytes":172},{"name":"tsconfig.json","path":"tools/inspector/tsconfig.json","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/inspector/tsconfig.json","title":"Inspector Skill","category":"anthropic-skill","format":"json","content":"# Inspector Skill\n\nPath: `tools/inspector/tsconfig.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/inspector/tsconfig.json)","tokens":300,"sizeBytes":174},{"name":"package.json","path":"typescript/agents/a2ui_agent/package.json","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/typescript/agents/a2ui_agent/package.json","title":"A2ui_agent Skill","category":"anthropic-skill","format":"json","content":"# A2ui_agent Skill\n\nPath: `typescript/agents/a2ui_agent/package.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/typescript/agents/a2ui_agent/package.json)","tokens":300,"sizeBytes":199},{"name":"tsconfig.check.json","path":"typescript/agents/a2ui_agent/tsconfig.check.json","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/typescript/agents/a2ui_agent/tsconfig.check.json","title":"A2ui_agent Skill","category":"anthropic-skill","format":"json","content":"# A2ui_agent Skill\n\nPath: `typescript/agents/a2ui_agent/tsconfig.check.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/typescript/agents/a2ui_agent/tsconfig.check.json)","tokens":300,"sizeBytes":213},{"name":"tsconfig.json","path":"typescript/agents/a2ui_agent/tsconfig.json","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/typescript/agents/a2ui_agent/tsconfig.json","title":"A2ui_agent Skill","category":"anthropic-skill","format":"json","content":"# A2ui_agent Skill\n\nPath: `typescript/agents/a2ui_agent/tsconfig.json`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/typescript/agents/a2ui_agent/tsconfig.json)","tokens":300,"sizeBytes":201},{"name":"GEMINI.md","path":".gemini/GEMINI.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.gemini/GEMINI.md","title":".gemini - Gemini Agent & Antigravity Instructions","category":"gemini-rule","format":"markdown","content":"# .gemini - Gemini Agent & Antigravity Instructions\n\nPath: `.gemini/GEMINI.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.gemini/GEMINI.md)","tokens":300,"sizeBytes":184},{"name":"README.md","path":"tools/build_catalog/README.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/README.md","title":"build_catalog Documentation","category":"plugin-manifest","format":"markdown","content":"# build_catalog Documentation\n\nPath: `tools/build_catalog/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/build_catalog/README.md)","tokens":300,"sizeBytes":186},{"name":"README.md","path":"tools/composer/README.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/README.md","title":"composer Documentation","category":"plugin-manifest","format":"markdown","content":"# composer Documentation\n\nPath: `tools/composer/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/composer/README.md)","tokens":300,"sizeBytes":171},{"name":"README.md","path":"tools/editor/README.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/editor/README.md","title":"editor Documentation","category":"plugin-manifest","format":"markdown","content":"# editor Documentation\n\nPath: `tools/editor/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/editor/README.md)","tokens":300,"sizeBytes":165},{"name":"README.md","path":"tools/inspector/README.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/inspector/README.md","title":"inspector Documentation","category":"plugin-manifest","format":"markdown","content":"# inspector Documentation\n\nPath: `tools/inspector/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/tools/inspector/README.md)","tokens":300,"sizeBytes":174},{"name":"codebase.blueprint.md","path":"blueprints/codebases/typescript/agents/a2ui_agent/codebase.blueprint.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/blueprints/codebases/typescript/agents/a2ui_agent/codebase.blueprint.md","title":"Subagent: codebase.blueprint","category":"subagent-persona","format":"markdown","content":"# Subagent: codebase.blueprint\n\nPath: `blueprints/codebases/typescript/agents/a2ui_agent/codebase.blueprint.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/blueprints/codebases/typescript/agents/a2ui_agent/codebase.blueprint.md)","tokens":300,"sizeBytes":271},{"name":"CHANGELOG.md","path":"typescript/agents/a2ui_agent/CHANGELOG.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/typescript/agents/a2ui_agent/CHANGELOG.md","title":"Subagent: changelog","category":"subagent-persona","format":"markdown","content":"# Subagent: changelog\n\nPath: `typescript/agents/a2ui_agent/CHANGELOG.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/typescript/agents/a2ui_agent/CHANGELOG.md)","tokens":300,"sizeBytes":202},{"name":"KNOWN_GAPS.md","path":"typescript/agents/a2ui_agent/KNOWN_GAPS.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/typescript/agents/a2ui_agent/KNOWN_GAPS.md","title":"Subagent: known_gaps","category":"subagent-persona","format":"markdown","content":"# Subagent: known_gaps\n\nPath: `typescript/agents/a2ui_agent/KNOWN_GAPS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/typescript/agents/a2ui_agent/KNOWN_GAPS.md)","tokens":300,"sizeBytes":205},{"name":"README.md","path":"typescript/agents/a2ui_agent/README.md","rawUrl":"https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/typescript/agents/a2ui_agent/README.md","title":"Subagent: readme","category":"subagent-persona","format":"markdown","content":"# Subagent: readme\n\nPath: `typescript/agents/a2ui_agent/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/typescript/agents/a2ui_agent/README.md)","tokens":300,"sizeBytes":193}],"systemPromptSnippet":"\n\n# AI Agent Protocol & Instructions\n\nPath: `AGENTS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/AGENTS.md)\n\n\n# swift - AI Agent Protocol & Instructions\n\nPath: `swift/AGENTS.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/swift/AGENTS.md)\n\n\n# eval - UI Design System & Style Tokens\n\nPath: `eval/DESIGN.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/eval/DESIGN.md)\n\n\n---\nname: a2ui-add-eval-datapoint\ndescription: Step-by-step workflow for adding and verifying new evaluation data points in the A2UI evaluation suite.\n---\n\n# Adding and verifying A2UI evaluation data points\n\nUse this skill when adding new data points or datasets to the A2UI evaluation framework in `eval/`.\n\n## References\n\nFor full architecture and setup details, consult:\n\n- `eval/CONTRIBUTING_USE_CASES.md`: The authoritative contributor guide for evaluation use cases, containing field definitions, context rules, and unencrypted multi-turn examples.\n- `eval/README.md`: Evaluation quickstart, Transcrypt setup, and CLI flags.\n- `eval/DESIGN.md`: Architecture, multi-stage scorers, and encryption-at-rest design.\n- `eval/datasets/dataset_schema.json`: Formal JSON Schema defining required fields and structural rules for evaluation data points.\n\n---\n\n## Step-by-step workflow\n\n### 1. Unlock Transcrypt\n\nDatasets in `eval/datasets/` are encrypted at rest. Unlock Transcrypt locally before authoring (ask an A2UI team member for the password):\n\n```bash\ncd eval\nbin/transcrypt -y -c aes-256-cbc -p \n```\n\n### 2. Author the data point\n\nCreate or update a dataset file in `eval/datasets/.yaml` (e.g. `eval/datasets/my_dataset.yaml`).\n\nEvery data point **must conform** to the JSON Schema in `eval/datasets/dataset_schema.json` and follow the authoring guidelines in `eval/CONTRIBUTING_USE_CASES.md`.\n\nFor a complete unencrypted reference example of a multi-turn conversation with system instructions, tool calls (including unrelated background tool calls), tool responses, and a judging target rubric, inspect `eval/examples/example_eval_case.json`.\n\n**Key authoring requirements from `eval/CONTRIBUTING_USE_CASES.md`:**\n\n- Include the full multi-turn conversation history (`messages`), including assistant function calls (`tool_calls`) and tool responses (`role: tool`). Do not use single-turn prompts.\n- Write the `target` as a qualitative judging rubric for the LLM-as-a-judge (what UI components must appear, data binding rules, and what errors to penalize). Do not include a hardcoded JSON string, as that ties the evaluation to a particular inference format.\n\n### 3. Validate schema compliance\n\nVerify that all data points satisfy `eval/datasets/dataset_schema.json`:\n\n```bash\ncd eval\nuv run python -m pytest tests/test_dataset.py\n```\n\n### 4. Run an evaluation on the new data point\n\nAlways execute an evaluation run on the newly added dataset to verify model inference and scoring:\n\n```bash\ncd eval\n# Quick validation on gemini-3.1-flash-lite\nuv run main.py --dataset my_dataset --sanity\n\n# Full evaluation check\nuv run main.py --dataset my_dataset\n```\n\nView the interactive traces and judging rationales:\n\n```bash\nuv run inspect view start\n```\n\n### 5. Verify encryption and commit\n\nWhen staging changes, Git applies the Transcrypt clean filter. Confirm that the staged file is encrypted ciphertext before committing:\n\n```bash\n# Stage the new dataset file\ngit add eval/datasets/my_dataset.yaml\n\n# Verify staged content is encrypted ciphertext (not plaintext)\ngit diff --cached eval/datasets/my_dataset.yaml\n\n# Commit the encrypted data point\ngit commit -m \"feat(eval): add my_dataset evaluation data points\"\n```\n\n\n# References Skill\n\nPath: `.agents/skills/a2ui-audit/references/gh-reference.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/a2ui-audit/references/gh-reference.md)\n\n\n---\nname: a2ui-audit\ndescription: Main coordination skill to run the blueprint compliance, documentation synchronization, and test quality audits, posting the combined results as a labeled GitHub issue.\n---\n\n# A2UI Compliance Verification Skill\n\nThis skill coordinates the execution of specification compliance, documentation\nsync, and test quality audits, and publishes the combined results as a GitHub issue.\n\nOther than writing a report and creating an issue, this skill is purely a\nread-only skill; no changes are to be made to the codebase. Do not attempt to\nfix issues.\n\n---\n\n## **Instructions**\n\n1. **Audit Codebase Blueprint Compliance**:\n - Execute `python3 blueprints/skills/a2ui-blueprint-compliance/scripts/check_compliance.py` to dynamically discover all 8 production codebases and generate the baseline Markdown status report.\n - Run the sub-skill [`a2ui-blueprint-compliance`](../../../blueprints/skills/a2ui-blueprint-compliance/SKILL.md) to audit each discovered codebase for missing features or blueprint drift.\n - Save the compiled Markdown report to a temporary file in the workspace (e.g., `compliance_report.md`) under the header `## Codebase Blueprint Compliance Audit`.\n\n2. **Audit Code vs. Documentation Synchronization**:\n - Run the sub-skill [`a2ui-doc-sync-check`](../a2ui-doc-sync-check/SKILL.md) to audit documentation drift across `docs/`, `specification/`, codebase READMEs, and inline docstrings.\n - Append the returned Markdown report to `compliance_report.md` under a new header `## Code & Documentation Sync Audit`.\n\n3. **Audit Test Quality & Assertion Strength**:\n - Run the sub-skill [`a2ui-test-quality-check`](../a2ui-test-quality-check/SKILL.md) to audit test suites across all codebases for weak assertions and behavioral verification.\n - Append the returned Markdown report to `compliance_report.md` under a new header `## Test Quality & Assertions Audit`.\n\n4. **Summarize the report**:\n - Add a `## Summary` section at the top of the `compliance_report.md` file with a detailed overview of the audit scope and key findings across all audited codebases.\n - Add a `## Recommendations` section listing actionable, prioritized follow-up items formatted as a numbered list (e.g. `1. **P0**: ...`). Each numbered item MUST represent a concrete, self-contained remediation task.\n - Immediately below the recommendations list, include the mandatory automated remediation callout:\n > 🤖 **Automated Remediation**: Comment `/fix ` (e.g., `/fix 1`) on this issue to have an agent create a draft PR for that recommendation.\n\n5. **Format and Detail Requirements**:\n - **MANDATORY COMPLETE REPOSITORY COVERAGE**: The report MUST include status rows and detailed findings for **ALL 8 production codebases** discovered by `check_compliance.py`. Do NOT truncate, shortcut, or abbreviate the summary tables or detailed findings.\n - For each audit section, provide specific evidence:\n - Exact file paths (e.g. `python/a2ui_agent/transport.py:L45-L60`).\n - Specific function/class names, parameter mismatches, or missing feature descriptions.\n - Concrete examples of weak assertions (e.g. `assert response is not None` in `eval/tests/test_strategies.py`).\n - Follow the structure provided in the **Report Format Template** below.\n\n6. **Publish Report**:\n - Execute the local Python helper script to create the GitHub issue containing the combined reports:\n ```bash\n python3 .agents/skills/a2ui-audit/scripts/create_compliance_report.py compliance_report.md --repo a2ui-project/a2ui\n ```\n - The publishing script will create the GitHub issue, automatically inject copyable remediation prompt blocks referencing the newly created issue URL under each recommendation item, and update the issue body.\n - Ensure the helper script runs successfully.\n - Clean up the temporary file `compliance_report.md` after completion.\n\n---\n\n## **Report Format Template**\n\nWhen compiling `compliance_report.md`, use the following structure:\n\n```markdown\n## Summary\n\n[Provide a 2-3 paragraph detailed summary explaining the repository state, key areas audited across SDKs, renderers, and tests, and major findings.]\n\n## Recommendations\n\n1. **[Priority]**: **[Title]**\n - [Clear detailed explanation of the fix needed, specifying affected directories or modules.]\n\n2. **[Priority]**: **[Title]**\n - [Clear detailed explanation of the fix needed, specifying affected directories or modules.]\n\n## Codebase Blueprint Compliance Audit\n\n| Codebase Implementation | Associated Module | Status | Commits Behind | Current Commit | Latest Commit |\n| ----------------------- | ------------------- | ------ | -------------- | -------------- | ------------- |\n| `path/to/codebase` | `associated_module` | Status | X | `commit_hash` | `latest_hash` |\n\n### Detailed Findings & Discrepancies\n\n- **[Codebase Path]**: [Detailed description of missing specifications, missing required features, or frontmatter commit hash drift.]\n\n## Code & Documentation Sync Audit\n\n| Directory | Status | Identified Issues |\n| ------------- | ------ | ----------------- |\n| `path/to/dir` | Status | Brief Summary |\n\n### Detailed Findings\n\n- **README Mismatches**:\n - `path/to/README.md`: [Exact invalid command or outdated setup step found in README.]\n- **Docstring / API Drift**:\n - `path/to/file.ext:L12-L34`: [Specific parameter or return type mismatch between implementation and docstring/comments.]\n\n## Test Quality & Assertions Audit\n\n| Suite / Module | Status | Observations |\n| --------------- | ------ | ------------- |\n| `path/to/tests` | Status | Brief Summary |\n\n### Detailed Findings\n\n- **Weak Assertions**:\n - `path/to/test_file.ext` (`test_function_name`): [Explanation of weak assertion, e.g. using `assertNotNull` instead of schema/type check.]\n- **Missing Edge Case Tests**:\n - `path/to/module`: [Boundary conditions, error cases, or invalid inputs that lack test coverage.]\n```\n\n---\n\n## **References**\n\n- Refer to the [`a2ui-blueprint-compliance`](../../../blueprints/skills/a2ui-blueprint-compliance/SKILL.md) skill for codebase blueprint checking.\n- Refer to the [`a2ui-doc-sync-check`](../a2ui-doc-sync-check/SKILL.md) skill for documentation sync checking.\n- Refer to the [`a2ui-test-quality-check`](../a2ui-test-quality-check/SKILL.md) skill for test quality and assertion checking.\n- Refer to the [`gh-reference`](./references/gh-reference.md) reference for GitHub CLI (`gh`) operations.\n\n\n---\nname: a2ui-doc-sync-check\ndescription: Auditing codebase implementations for synchronization drift with the user documentation, readmes, and code comments.\n---\n\n# A2UI Code and Documentation Synchronization Check Skill\n\nThis skill guides the process of auditing concrete codebase implementations to verify that they are synchronized with their respective documentation files, codebase READMEs, and inline code comments/docstrings.\n\n---\n\n## **Instructions**\n\n1. **Locate Documentation and Readmes**:\n - Find all user guides, tutorials, and specifications under `docs/` and `specification/`.\n - Find the `README.md` files in each codebase directory.\n\n2. **Audit Readme Commands and Configs**:\n - For each codebase directory, parse the `README.md` to extract setup commands, dependencies, build/test commands, and directory layouts.\n - Cross-reference these details with the codebase's project files (e.g. `package.json`, `pyproject.toml`, `pubspec.yaml`, `Package.swift`).\n - If any command listed in the readme is invalid, deprecated, or has wrong arguments, list it as a discrepancy.\n\n3. **Audit Code-vs-Docs Public API and Settings**:\n - Make sure the glossary is respected. Verify that terms used in code, documentation and blueprints are consistent with [the glossary](../../../docs/public/concepts/glossary.md). If you find deviations, suggest fixes. If you see an important term is used in documentation and/or API, but is missing from the glossary, suggest an update for the glossary.\n - Inspect the codebase's public API entrypoints (classes, interfaces, types, methods).\n - Compare them against any descriptions, structural maps, or code snippets in the `docs/` folder.\n - Look for renamed classes, changed signatures, or removed options that are still described in the docs.\n - If the codebase exposes new settings or flags that are undocumented in `docs/` or the spec guides, log them as missing documentation.\n\n4. **Audit Inline Comments and Docstrings**:\n - Audit inline comments and docstrings (e.g. JSDoc in TS, docstrings in Python, triple-slash comments in Dart/Swift) for public APIs.\n - Flag any mismatch where code parameter names, types, return behaviors, or exceptions thrown deviate from what the docstring claims.\n\n5. **Links and Duplicates**:\n - When an artifact (code, document, issue, PR, comment and so on) is referenced, make sure it has a link.\n - When a glossary term is used - link the first occurrence of the term to the glossary entry if it exists.\n - Make sure there is no duplications of content. If you find some, delete the duplicate and leave a reference.\n\n6. **Conciseness and Clarity**:\n - Verify that documentation and code comments follow the [natural-writing](../natural-writing/SKILL.md) skill, and flag text that breaks its rules.\n\n7. **Format the Report**:\n - Build a Markdown report summarizing the findings:\n - Table of audited directories.\n - **Documentation Drift**: Mismatches between documentation guides (`docs/`) and codebase implementations.\n - **Readme Errors**: Invalid setup, compile, or test commands found in `README.md` files.\n - **Docstring Mismatches**: Outdated parameter names or behaviors described in inline comments.\n - Return this Markdown report as your final response.\n\n\n---\nname: a2ui-generate-pydantic-models\ndescription: Automated generator for strongly typed Pydantic v2 data models and basic catalogs across any A2UI protocol version (v0.8, v0.9, v0.9.1, v1.0, etc.).\n---\n\n# A2UI Pydantic Model Generation Skill\n\nThis skill provides an automated code generation tool that produces strongly typed Pydantic v2 data models and basic catalog definitions for `python/a2ui_core` directly from the schemas and catalogs in `specification//`.\n\n---\n\n## Agent Execution Steps\n\nWhen given a prompt like _\"Generate Pydantic model classes for A2UI spec v1.0\"_:\n\n1. **Extract the target version parameter from the prompt** (e.g. `v1.0` -> `v1.0`).\n\n2. **Execute the generator script exactly once for that target version**:\n\n ```bash\n uv run python .agents/skills/a2ui-generate-pydantic-models/scripts/codegen_pydantic.py --version \n ```\n\n _(Replace `` with the single requested version, e.g. `--version v1.0`)_.\n\n3. **Format generated Python code**:\n\n ```bash\n cd python/a2ui_core\n uv run pyink .\n ```\n\n4. **Verify the generated files** by running pytest:\n\n ```bash\n cd python/a2ui_core\n uv run pytest tests/test_codegen_pydantic.py\n ```\n\n5. **Stop and report completion to the user.**\n\n---\n\n## Generated Output Files per Version\n\nWhen executed for a target version `` (e.g. `v1.0` -> `v1_0`), the script generates:\n\n1. **`python/a2ui_core/src/a2ui/core/schema//`**:\n - `constants.py`\n - `common_types.py`: strongly typed shared models and the `COMMON_TYPES_DEFS` manifest, which maps each spec `$defs` name to its symbol in spec order. No spec schema is copied verbatim; the published common types schema is rebuilt from these symbols.\n - Type aliases such as `ComponentId`, `Child`, `ChildList` and the `Dynamic*` unions are registered as `Annotated[..., Field(description=...)]` with the spec descriptions, so the runtime JSON schema generator needs no per-def special cases. Dynamic unions list their members in spec order.\n - When a `Dynamic*` def constrains its function-call branch with a `returnType` const, the branch is `Annotated[FunctionCall, ReturnType(\"\")]`, which validates the return type and emits the spec's `allOf` in both modes. Any other branch shape fails generation.\n - Every model extends `SpecBaseModel` (hand-written in `schema/common_types.py`) and has no generated methods. Keywords that fields cannot produce are declared in the model config as `json_schema_extra=SchemaKeywords(...)`: it drops `additionalProperties` where the spec leaves it out and adds `returnType`, `unevaluatedProperties`, `title`, `allowedParents` and `oneOf` required-alternatives (see `_SPEC_KEYWORDS`). The keywords apply only to the declaring model, not to subclasses. `SpecBaseModel` validates a declared `oneOf` whose branches only list required fields (for example `FunctionResponse`'s `value`/`error`), requiring exactly one branch.\n - Only composition that references the catalog's function union is limited to `spec_schema()` (`SchemaKeywords(..., spec_only=True)`), which the published common types schema uses: v0.9's `FunctionCall` `oneOf`, v1.0's `FunctionCall` `allOf` over `FunctionCommon` and `anyFunction` (`replace=True`, since the spec def is pure composition), and v0.9's precise `args` shape (a schema-only `JsonSchemaAs` annotation requested through the `x-python-type` property override). Catalogs keep the flat model shape there. References inside declared keywords are the markers `def_ref(\"\")` and `catalog_functions()` from the internal `a2ui.core.schema._json_schema` module, which the schema builder resolves to `$ref`s. `FunctionCall` itself is a flat model that validates any call without the catalog.\n - Nested object properties with their own properties become helper models named `` (for example `ComponentCommonMetadata`, `IndexSystemFunctionArgs`, `FunctionResponseError`), which schemas inline. Wrapper unions such as `Action` are `TypeAliasType`s, so fields reference them by def name. Each branch gets a `Wrapper` model, and a branch property that is an object becomes `` (`ActionEvent`, `ActionEventWrapper`, `ActionFunctionCallWrapper`). A generated name that collides with a def, a base symbol or another helper fails generation.\n - A def that the spec leaves open (no `additionalProperties` and no `unevaluatedProperties: false`) allows extra keys. `ComponentCommon` is the exception (`_SUBCLASSED_DEFS`): generated catalog components subclass it and must stay closed.\n - Optional fields are typed `X | None` so they can be absent. `SpecBaseModel` rejects an explicit null for such a field unless `X` accepts null itself (`Any`), under both the spec name and the Python field name; it does not change the JSON schema. Catalog components inherit this rule through `ComponentCommon`. v0.9's `FunctionCall.args` also rejects null values.\n - Primitive defs such as `CallId` are `TypeAliasType`s, so local references keep their `$ref`. References from other documents to a primitive def map to its Python type through `_CROSS_DOCUMENT_REF_TYPES` in `engine.py`.\n - `patternProperties` objects (`Extensions`) are `TypeAliasType`s over a key-checking validator, and their pattern is published in the spec schema and in catalogs. Python's `re` cannot compile `\\p{...}`, so the SDK validates JSON schemas with `a2ui.core.validation.SchemaValidator` (powered by `regex`). The `DynamicValue` literal-object branch carries the spec's `propertyNames` and `not` clauses through a `SchemaKeywords` annotation in both modes.\n - Common types keep `component` properties (`Surface`) and emit required consts without defaults (`skip_component_property` and `required_const_default` on the engine). Spec defaults are emitted as JSON schema `default` values (`schema_defaults`), not as description notes.\n - Common types are generated in strict mode: a schema shape the models would not enforce (an unknown or non-local `$ref`, siblings next to `$ref`/`const`/composition, an unsupported keyword next to `properties`, a required property that is not declared, an empty union) raises instead of loosening validation. Output is deterministic and does not depend on string hashing.\n - `agent_to_renderer.py` / `server_to_client.py`: strongly typed outbound message models and the `AGENT_TO_RENDERER_DEFS` manifest, which maps each spec `$defs` (or v0.8 `properties`) name to its symbol in spec order so `get_agent_to_renderer_schema_map` / `get_agent_to_renderer_schema_json` can rebuild `server_to_client.json` / `agent_to_renderer.json` from the models. Nested payload objects and array item objects become helper models marked with `INLINE_DEF_MARKER` (for example `CreateSurfaceMetadata`, `SurfaceUpdateComponentsItem`), and non-message `$defs` (`Component`, `ComponentsList`) are emitted as `TypeAliasType`s with `SchemaKeywords`.\n - `renderer_to_agent.py` / `client_to_server.py`\n - `renderer_capabilities.py` / `client_capabilities.py`\n - `agent_capabilities.py` / `server_capabilities.py` (when present in spec)\n - `catalog_definition.py` (when present in spec)\n - `__init__.py`\n\n2. **`python/a2ui_core/src/a2ui/core/basic_catalog//`**:\n - `components.py` (strongly typed components & `ModelComponentApi` registrations)\n - `function_apis.py` (strongly typed function schemas & `FunctionApi` classes)\n - `styles.py` (theme schema, generated when theme is defined in catalog)\n - `__init__.py`\n - The models and the generated `BasicCatalog` carry everything `Catalog.to_json()` needs to rebuild the published catalog document from them, with no catalog JSON copied into Python or read at runtime:\n - `BasicCatalog` passes the document's top-level fields to `Catalog`: `$schema`, `$id`, `title`, `description`, `protocolVersion` (None when the document declares none), `catalogId` when it declares none, `instructions`, where it writes its theme (`theme_location`), its unions (`union_defs`, which must list the catalog's entries) and the document its common types references point into (`common_types_uri`). The theme is passed as `theme_model`.\n - Without common types (v0.8), nested objects become models that keep the document's shapes: two nested objects of different shapes never share a model (the later one is prefixed with its component or parent model, for example `SliderValueItem`), and their descriptions stay on the fields, with line breaks, rather than becoming docstrings. `Catalog.to_json()` writes them inline, as the v0.8 document does.\n - For versions with a common types schema (v0.9+), the models carry everything `Catalog.validation_schema` and `Catalog.to_json()` need to rebuild the specification's `catalog.json` shape from them:\n - A component's `allOf` references to common types defs (for example `Checkable`) become base classes, and catalog defs (`CatalogComponentCommon`) become base models. A component with more than one base sets `extra=\"forbid\"`, because Pydantic would otherwise inherit an open base's config. A component description becomes the class docstring and fails generation if it cannot be one.\n - A function's description becomes the `FunctionApi.description` attribute. Keywords on the `args` object that fields cannot produce (`unevaluatedProperties`, `additionalProperties`, required-alternative `anyOf`) are declared with `SchemaKeywords` as the model's `json_schema_extra`, and an unknown keyword fails generation.\n - Field constraints (`minItems`, `minimum`, ...) are emitted as `Field` arguments, so they are validated and published; `format` and `default` are published through `json_schema_extra`. An `allOf` member that only adds keywords becomes a `SpecAllOf` annotation.\n - The conformance cases `test_v08_basic_catalog_to_json`, `test_v09_basic_catalog_to_json` and `test_v10_basic_catalog_to_json`, and `python/a2ui_core/tests/test_basic_catalog_documents.py`, compare `BasicCatalog().to_json()` with the published files, so any drift fails the tests.\n\n3. **`python/a2ui_core/src/a2ui/core/schema/__init__.py`**:\n - Registers the version in `A2uiProtocolVersion` enum and updates envelope unions.\n\n\n---\nname: a2ui-implement-new-sdks-for-client-language\ndescription: Step-by-step phased instructions for building new A2UI Core SDKs, Framework Adapters, and Inference SDKs from scratch in any client language.\n---\n\n# A2UI SDK Implementation Guide (Phased Execution)\n\nThis skill provides expert instructions and sequences for AI agents or contributors tasked with implementing A2UI Core SDKs, Framework Adapters, or Agent/Inference SDKs in a new programming language or UI framework.\n\n---\n\n## **1. Core State SDK Phases**\n\nIf you are building a new **Core SDK** (e.g., in Rust, Swift, Go, or C++), you must follow this sequence of phases:\n\n### **Phase 1: Context & Schemas Ingestion**\n\nThoroughly review:\n\n- `blueprints/modules/a2ui_core.blueprint.md` (for state and message structures).\n- `specification/v1_0/json/common_types.json` (dynamic binding schemas).\n- `specification/v1_0/json/server_to_client.json` (message envelopes).\n- `catalogs/basic/v1/catalog.json` (target components catalog).\n\n### **Phase 2: Technical Architecture Planning**\n\nCreate a detailed, local architectural proposal detailing:\n\n- **Dependencies**: Which Schema library and Observable/Reactive library will you use? Note that the reactive library must support both discrete event subscription and stateful, signal-like data streams (e.g., BehaviorSubject/Signal).\n- **Component APIs**: How will you define the `ComponentApi` interface in this language?\n- **Binding Strategy**: How will you structure the abstract Core Binder Layer?\n- _STOP and obtain human reviewer approval on this plan before writing code._\n\n### **Phase 3: Core Model Layer**\n\nImplement the framework-agnostic data and processor layers:\n\n1. **Observables & Signals**: Implement multi-cast reactive streams with clear unsubscribe mechanism to prevent leaks.\n2. **Protocol Structures**: Create strictly-typed native classes/structs representing `A2uiMessage` envelopes and client capabilities with serialization/deserialization.\n3. **DataModel & JSON Pointers**: Implement relative/absolute path resolution, auto-vivification (auto-typing intermediate segments), and bubble/cascade path change notifications.\n4. **Core State Models**: Implement `ComponentModel`, `SurfaceComponentsModel`, `SurfaceModel`, and `SurfaceGroupModel`.\n5. **Context Mapping**: Implement `DataContext` and `ComponentContext`.\n6. **MessageProcessor**: Ingest incoming messages and mutate the state models. Generate `inlineCatalogs` client capabilities.\n7. **Verification**: Write comprehensive unit tests for pointer cascading, JSON deserialization/validation, and message dispatching.\n\n### **Phase 4: Foundational Basic Catalog Support**\n\nBootstrap support for the Basic Catalog:\n\n- **Foundational Components**: Define the pure API schemas and Binders for: `Text`, `Row`, `Column`, `Button`, and `TextField`.\n- **Foundational Functions**: Implement `formatString` to interpret `${expression}` syntaxes, supporting recursive token evaluations and reactive coercion.\n- **Verification**: Ensure properties update reactively when underlying data paths emit notifications.\n\n### **Phase 5: Complete Basic Catalog Support**\n\n- **Full Components & Binders**: Define core binders for all other components in `basic/catalog.json`.\n- **Full Functions**: Implement remaining basic mathematical, logical, and array operations.\n- **Validation**: Ensure strict type coercion rules are satisfied and memory disposals work flawlessly.\n\n---\n\n## **2. Framework Adapter SDK Phases**\n\nIf you are building a new **UI Framework Adapter / Renderer** (e.g., in Flutter/Dart, SwiftUI, Jetpack Compose, Vue, or Svelte), follow this sequence:\n\n### **Phase 1: Ingestion & Core Integration**\n\nReview:\n\n- `blueprints/modules/a2ui_framework_adapter.blueprint.md` (View and rendering architecture).\n- `catalogs/basic/v1/basic_catalog_implementation_guide.md` (spacing, alignment, and typography specifications).\n\n### **Phase 2: Architectural Plan**\n\nDraft a plan specifying:\n\n- **Component Registry**: How components are dynamically resolved and instantiated.\n- **Surface Widget**: How the root canvas mounts and recurses through the layout tree starting at `root`.\n- **Observer/State Bridge**: Which Strategy (Direct, Predefined Binders, or Automated wrappers) will connect core signals to native views.\n- _STOP and obtain human reviewer approval on this plan._\n\n### **Phase 3: Adapter & Lifecycle Layer**\n\n- Implement `ComponentImplementation` base traits/classes.\n- Implement the framework-native `Surface` entrypoint widget.\n- Implement subscription management: lazy-subscribing only on mount, handling path stability updates, and strictly calling `dispose()` on unmount.\n\n### **Phase 4: Bootstrapping Basic Catalog Rendering**\n\n- Build native visual elements for: `Text`, `Row`, `Column`, `Button`, and `TextField`.\n- Bundle these elements into the first framework catalog adapter.\n- Verify reactive layout properties dynamically.\n\n### **Phase 5: Gallery Application Milestone**\n\nBuild the **Gallery App** as a testing playground with:\n\n- Left Column: Sample navigation.\n- Center Column: Surface preview, JSON message stream, and step-by-step interactive message stepper.\n- Right Column: Live data model inspect pane and action logger.\n- Load the 5 foundational verification examples: `00_simple-text.json`, `00_row-layout.json`, `00_complex-layout.json`, `00_interactive-button.json`, and `00_simple-login-form.json`.\n- _STOP and obtain human reviewer approval of the UI and visual rendering performance._\n\n### **Phase 6: Full Catalog Support**\n\n- Implement all remaining widgets (e.g. Card, Image, List, etc.) and validation traits like `Checkable`.\n- Update the Gallery App to support all official examples in `catalogs/basic/v1/examples/`.\n- Run visual parity and event action tests to verify correctness.\n\n\n# A2ui-issue-triage Skill\n\nPath: `.agents/skills/a2ui-issue-triage/README.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/a2ui-issue-triage/README.md)\n\n\n# References Skill\n\nPath: `.agents/skills/a2ui-issue-triage/references/triage_criteria.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/a2ui-issue-triage/references/triage_criteria.md)\n\n\n---\nname: a2ui-issue-triage\ndescription: Automates the triage of GitHub issues in the A2UI repository. Helps the oncall engineer by fetching untriaged issues, generating AI-suggested priorities, assignees, and responses, launching a local review dashboard, and bulk-applying approved decisions to GitHub. Use when tasked with triaging new GitHub issues or managing the repository backlog.\n---\n\n# A2UI GitHub Issue Triage Skill\n\nThis skill guides the process of fetching, analyzing, reviewing, and applying triage decisions to GitHub issues in the A2UI repository using a local interactive dashboard.\n\n> [!IMPORTANT]\n> **WRITING GUIDELINES**\n> When drafting replies, explanations, or any prose, refer to the [natural-writing](../natural-writing/SKILL.md) skill to ensure clarity, accuracy, and tone.\n\n---\n\n## Workflow\n\nFollow these steps to triage new or backlog issues:\n\n### Step 1: Fetch Untriaged Issues\n\nUse the fetch script to retrieve all open issues lacking a priority label (`P0`, `P1`, `P2`, `P3`, `P4`) in the A2UI repository.\n\n1. Run the fetch script to download the issues to a raw JSON file in your conversation-specific scratch directory:\n `python3 .agents/skills/a2ui-issue-triage/scripts/fetch_issues.py --repo \"a2ui-project/a2ui\" --output-file \"/brain//scratch/raw_issues.json\"`\n\n---\n\n### Step 2: Analyze and Suggest Triage\n\nProcess the raw issues and generate recommended triage fields based on the project's triage criteria.\n\n1. Read the triage criteria reference document: [triage_criteria.md](references/triage_criteria.md) and repository canonical templates: [triage-templates.md](../../../docs/contributing/triage-templates.md).\n2. For each issue in `raw_issues.json`, evaluate its description and comments to determine:\n - **Priority**: `P0` (Urgent), `P1` (High), `P2` (Medium), `P3` (Low), `P4` (Unplanned/Out of Scope), or `None`. `P0` and `P1` require assignees.\n - **Assignee**: Recommended owner based on the affected component or area.\n - **Action**: `investigate`, `assign_and_fix`, `needs_info`, `backlog`, `close_duplicate`, `close_invalid`, or `close_resolved`.\n - **Labels**: Applicable repository labels (e.g. `type: bug`, `component: lit renderer`, `status: first-line-handled`, `status: waiting-for-author-response`).\n - **Reply**: A polite, structured draft response addressing the author using canonical templates.\n3. If an issue is a potential duplicate, perform at most three targeted GitHub searches to find matching canonical issues before suggesting `close_duplicate`.\n4. **Natively Orchestrate Subagents**: Instead of running a Python script to spawn subagents (which can fail due to local workstation gRPC credential policies), the parent agent should natively orchestrate the parallel evaluations:\n - Load the first N issues (defaulting to 10, or as requested) from `raw_issues.json`.\n - Call the `invoke_subagent` tool in parallel for those issues. Prompt each subagent to analyze its assigned issue against the guidelines in [triage_criteria.md](references/triage_criteria.md) and return a structured JSON block containing `priority`, `action`, `labels`, and `reply`.\n - Once all subagents report back, compile their recommendations into the standard schema:\n - Map component labels to suggested assignees using git log history if necessary, and include a short sentence in `assignee_reason` explaining why they were chosen (e.g., \"Suggesting gspencer because they recently modified related code\").\n - Inject `total_issues_count` (preserving the total count from the raw issues JSON).\n - Save the final compiled payload to `issues_to_triage.json` in the scratch directory.\n\n---\n\n### Step 3: Launch Review Dashboard\n\nLaunch the interactive web dashboard to allow the oncall engineer to review and refine the suggested triages.\n\n1. Start the local server as a background task, pointing it to your scratch directory:\n `python3 .agents/skills/a2ui-issue-triage/scripts/launch_dashboard.py --data-file \"/brain//scratch/issues_to_triage.json\" --output-file \"/brain//scratch/triage_decisions.json\"`\n Set `WaitMsBeforeAsync` to `1000` so the server runs in the background.\n2. **Wait for Completion**: Stop calling tools and go idle. The launcher will automatically open the browser for the user and block until they click \"Apply Triages\" or \"Abort\". Once the user acts, the background task will complete, and you will receive a notification with the exit status.\n3. **Verify Exit Status**:\n - If the task exited with status `0` (approved), proceed to apply the decisions.\n - If the task exited with a non-zero status (abort), don't modify any issues. You MUST STOP and ask the user for further instructions.\n\n---\n\n### Step 4: Apply Decisions to GitHub\n\nOnce the dashboard task exits successfully, **Execute Approved Decisions**: Run the apply script to update the approved labels, assignees, and comments on GitHub:\n\n`python3 .agents/skills/a2ui-issue-triage/scripts/apply_triage.py --decisions-file \"/brain//scratch/triage_decisions.json\"`\n\n---\n\n## Bundled Resources\n\n- **[triage_criteria.md](references/triage_criteria.md)**: Authoritative guide for classifying issues, assigning priorities, and drafting response messages.\n- **`scripts/fetch_issues.py`**: Script to query open, untriaged issues via the GitHub CLI.\n- **`scripts/suggest_triage.py`**: Helper script to generate initial triage suggestions.\n- **`scripts/launch_dashboard.py`**: Local HTTP server that opens the interactive web dashboard in the user's browser.\n- **`assets/triage_dashboard.html`**: HTML/CSS/JS template for the triage review interface.\n- **`scripts/apply_triage.py`**: Script to apply finalized triage decisions to GitHub.\n\n\n---\nname: a2ui-release-python\ndescription: Releases the Python SDKs (a2ui-core, a2ui-agent-sdk, a2ui-a2a, a2ui-adk) to PyPI by running preflight checks, dispatching the release workflow as a dry run, confirming with the maintainer, publishing, and following the changelog pull request through to merge. Use when asked to cut, publish, or release a Python SDK version.\n---\n\n# Releasing the A2UI Python SDKs\n\nThis skill turns a one-line request such as _\"release a2ui-core patch\"_ or\n_\"release the Python SDKs\"_ into the full release sequence.\n\nPublishing is done by the\n[Release Python SDKs](../../../.github/workflows/release-pypi.yml) workflow. This\nskill does not reimplement any of it. Its job is the part the workflow cannot do\nfor itself: choosing the bump, catching the problems that a workflow run would\ndiscover too late, and following through afterwards.\n\nBackground for anything not covered here:\n[docs/contributing/release.md](../../../docs/contributing/release.md).\n\n> [!CAUTION]\n> **Publishing to PyPI is irreversible.** A version can be yanked but never\n> reused or deleted. Step 5 is a mandatory stop. Never dispatch a run with\n> `dry_run: false` without an explicit go-ahead from the maintainer in the\n> current conversation.\n\n### What runs where\n\n**The workflow performs the release. Nothing here does.** Building, tagging,\npushing tags, staging in the Artifact Registry and triggering the Exit Gate all\nhappen inside `release-pypi.yml`, and only there. It could not be otherwise: the\nExit Gate authenticates by matching the OIDC claim\n`…/release-pypi.yml@refs/heads/main`, so a local upload has no credentials to\nuse.\n\n| Run locally | Run by the workflow |\n| :--------------------------------------------- | :------------------------------------------------ |\n| `release_version.py notes` | `release_version.py plan` (authoritative) |\n| `release_version.py plan` (preview only) | `release_version.py check` |\n| `release_version.py check` (preview only) | `release_version.py cut-changelog` |\n| `gh workflow run`, `gh run view`, `gh pr list` | `release_artifacts.py`, `confirm_pypi.py` |\n| | `uv build`, `twine upload`, `git tag`, `git push` |\n\nThe local calls are limited to the read-only subcommands `notes`, `next`,\n`current`, `tag`, `plan` and `check`. They exist to answer two questions before\nspending a CI run: is there anything to release, and will preflight reject it.\n\n> [!IMPORTANT]\n> A local `plan` is a **prediction**, not the release. It is computed from the\n> tags in the local checkout, so it is only as current as the last fetch — which\n> is why Step 2 fetches first. The plan the workflow computes is the one that\n> counts, and Step 4 reads it back out of the run before anyone approves it.\n\nNever run `cut-changelog --write`, `git tag`, `git push`, `uv build` or `twine`\nby hand to perform a release. If the workflow cannot do it, fix the workflow.\n\n> [!IMPORTANT]\n> One exception, and it is deliberate: **the changelog pull request has to be\n> opened by a person, not by the workflow.** GitHub does not start workflow runs\n> for events caused by `GITHUB_TOKEN`, so a pull request the workflow opened\n> would never get the required checks and could never be merged. The workflow\n> pushes the branch; Step 7 opens the pull request.\n\n## Step 1: Check environment prerequisites\n\nCheck that your local environment meets these prerequisites before proceeding.\nThe preflight check in Step 3 (`release_version.py check`) also validates these\nautomatically and stops with an `Action needed:` message for each one that\nfails. They are skipped in GitHub Actions, where they do not apply.\n\n1. **An a2ui checkout.** Run from your clone of `a2ui-project/a2ui`. The script\n finds the repository root itself, so a subdirectory works (it warns), but\n the commands below use paths relative to the root.\n2. **Python 3.11+.** The script reads `pyproject.toml` with the standard\n library `tomllib`. If your system `python3` is older, run it through the\n project toolchain instead: `uv run python .github/scripts/release_version.py\n...`.\n3. **GitHub CLI (`gh`)**, installed, authenticated with `github.com`, and with\n write access to `a2ui-project/a2ui`. It dispatches and watches the workflow\n and opens the changelog pull request.\n4. **Git identity.** `git config user.name` and `git config user.email` must be\n set, so the changelog commit and pull request pass CLA verification.\n5. **A remote that points at `a2ui-project/a2ui`.** It may be called `origin`\n in a direct clone or `upstream` beside a fork; the script finds it by URL.\n The commands below call it `${REMOTE}`:\n\n ```bash\n REMOTE=$(git remote -v | awk '/a2ui-project\\/a2ui(\\.git)?\\/? \\(fetch\\)/ {print $1; exit}')\n ```\n\n---\n\n## Step 2: Work out what is being released\n\nTwo things are needed: `PACKAGE` and `BUMP` (`patch`, `minor`, or `major`).\n`PACKAGE` names the packages to release, either as a comma-separated list of\npackage names or as `all`:\n\n- One package: `a2ui-agent-sdk`\n- Several packages: `a2ui-a2a,a2ui-adk`\n- Every package: `all` (`a2ui-core`, `a2ui-agent-sdk`, `a2ui-a2a`, `a2ui-adk`)\n\nThe workflow publishes the listed packages in dependency order (`a2ui-core`,\n`a2ui-agent-sdk`, `a2ui-a2a`, `a2ui-adk`), whatever order they are listed in.\nDerive `PACKAGE` and `BUMP` from the changelogs. Never infer them from the\nphrasing of the request.\n\nFetch first. Versions are derived from tags, so every number below is wrong if\nthe checkout is behind:\n\n```bash\ngit fetch \"${REMOTE}\" main --tags\n```\n\n```bash\nfor package in a2ui-core a2ui-agent-sdk a2ui-a2a a2ui-adk; do\n echo \"== ${package}\"\n python3 .github/scripts/release_version.py notes --package \"${package}\"\ndone\n```\n\n**Choose the packages.** Release only those with a non-empty `## Unreleased`.\nEmpty output means that package has nothing to release, whatever was asked for.\nA plural request such as _\"release the Python SDKs\"_ does not mean `all`. List\nexactly the packages with pending entries, for example\n`a2ui-agent-sdk,a2ui-a2a`. If only one has pending entries, that one is the\nrelease. If none does, stop and say so.\n\nCheck the exit status, not just the output. The two failure shapes are\ndifferent answers:\n\n| Result | Meaning | Do |\n| :------------------------- | :---------------------------------------------------------------- | :----------------------------------- |\n| exit 0, output | Entries pending | Release this package |\n| exit 0, no output | `## Unreleased` is empty | Skip this package |\n| exit 1, `error:` on stderr | Changelog is malformed, usually a missing `## Unreleased` heading | Stop. Report it and do not dispatch. |\n\n> [!NOTE]\n> Dispatching a package whose `## Unreleased` is empty is not dangerous, just wasteful. The\n> plan builds, then preflight rejects the empty package and the run fails\n> several minutes in. The check above costs a second.\n\n**Choose the bump.** Read the entries. Fixes only means `patch` and new\nfeatures mean `minor`. A breaking change means `minor` while the package is\nbelow 1.0, and `major` from 1.0 on. Preview the result with `plan`,\nwhich returns exactly what the workflow will compute — version, tag and release\nnotes for every selected package:\n\n```bash\npython3 .github/scripts/release_version.py plan --package \"${PACKAGE}\" --bump \"${BUMP}\"\n```\n\n> [!IMPORTANT]\n> **One run applies one bump level to every listed package.** The workflow\n> takes a single `bump` input, so `build_plan` raises every version by the same\n> amount. When the packages warrant different levels — say fixes in\n> `a2ui-core` and a feature in `a2ui-agent-sdk` — there is no single right\n> answer. Put the choice to the maintainer:\n>\n> - **Take the higher level for every listed package.** One release, one\n> changelog pull request. The cost is an over-bumped version on the quieter\n> packages.\n> - **Run one release per bump level.** Correct versioning, but the changelog\n> pull request from each run must be **merged before starting the next**, or\n> the Step 3 guard will block it. Release in dependency order: `a2ui-core`,\n> `a2ui-agent-sdk`, `a2ui-a2a`, `a2ui-adk`.\n\n> [!IMPORTANT]\n> **A minor or major `a2ui-core` bump may need a pin change first.**\n> `a2ui-agent-sdk` declares a range such as `a2ui-core>=0.3.0,<0.4.0` in\n> [a2ui_agent/pyproject.toml](../../../python/a2ui_agent/pyproject.toml). If\n> the proposed `a2ui-core` version falls outside it, widen the pin in its own\n> pull request and **merge it to `main` before dispatching**. The workflow\n> releases `main` as it is and cannot change package files during the run.\n> Step 3 rejects the release until this is done.\n>\n> The same applies down the chain: `a2ui-a2a` and `a2ui-adk` pin\n> `a2ui-agent-sdk` in their `pyproject.toml`, and `a2ui-adk` pins `a2ui-a2a`\n> in its `a2a` extra. A new version of a package must fall inside every pin on\n> it.\n\n> [!IMPORTANT]\n> **A dependent needs its dependencies on PyPI.** Releasing `a2ui-a2a` or\n> `a2ui-adk` on its own requires the released `a2ui-agent-sdk` (and, for\n> `a2ui-adk`, `a2ui-a2a`) to satisfy its pins already. If it does not, release\n> the dependency first, or list it in the same run. Step 3 reports\n> this as \"has not been released yet\" or \"requires ..., but the latest release\n> ... is ...\".\n>\n> **First release of a brand-new package.** A package with no tag yet starts\n> from `0.0.0`, so use a `minor` bump to release `0.1.0`. Before its first\n> release, the package name must be added to the OSS Exit Gate allowlist for\n> `a2ui/pypi` and registered as a **Pending Publisher** on\n> `https://pypi.org/manage/account/publishing/` under the **Google** tab with\n> email `a2ui-py@oss-exit-gate-prod.iam.gserviceaccount.com` and an empty\n> subject (see `go/a2ui-release#pypi`). PyPI indexes Google Cloud Pending\n> Publishers uniquely by `(email, sub)`, so **only one Pending Publisher can be\n> registered at a time**. Do not release two brand-new packages in the same\n> manifest: register and publish them one at a time so the first upload\n> promotes its Pending Publisher to a project-scoped Trusted Publisher before\n> registering the second.\n\nPut the proposal to the maintainer with `ask_question`, showing the pending\nentries and the resulting versions, and let them correct it.\n\n---\n\n## Step 3: Preflight locally\n\nThese checks cost seconds and catch the failures that are expensive to hit\nmid-run. Run all of them before dispatching anything.\n\n**1. The environment and the checkout.** `check` runs these for you (see\nStep 1: Check environment prerequisites); this is what it looks for and why:\n\n- **No outstanding changelog branch** from a previous release on `${REMOTE}`.\n Until the last release's changelog lands, its entries are still under\n `## Unreleased`, and this release would repeat them. It checks the branch,\n not the pull request, because the release stops at the branch and there may\n be no pull request yet. The repository deletes branches on merge, so no\n branch means the last changelog landed. If one is found, get that change\n merged (open the pull request if nobody has), then start over from Step 2,\n because the pending entries will have changed.\n- **The released packages match `${REMOTE}/main`.** The workflow builds from\n `main`, so `python/a2ui_core`, `python/a2ui_agent`, `python/a2ui_a2a` and\n `python/a2ui_adk` must be identical to it.\n Uncommitted edits, or a local commit that is not merged yet (a widened pin,\n say), would make the local preview describe a release that is not the one\n that will go out. Other paths in the checkout do not matter.\n\nIf it reports any of these, or any of the Environment Prerequisites, stop and\nsay what was found.\n\n**2. The repository's own preflight passes.** The package checks (changelog,\ntag, and pin) are the ones the workflow runs, so a failure in them here is a\nfailure there:\n\n```bash\n# Check using bump level (comma-separated package names, or 'all'):\npython3 .github/scripts/release_version.py check --package \"${PACKAGE}\" --bump \"${BUMP}\"\n\n# Or check a specific version directly (single package only):\npython3 .github/scripts/release_version.py check --package \"${PACKAGE}\" --version \"${VERSION}\"\n```\n\nIt rejects an empty `## Unreleased`, a version that already has a tag, a version\noutside the range that another package pins it to, and a dependency on another\npackage of this repository that no released version (or no version in the same\nrun) satisfies. With several packages and `--bump`, it evaluates every listed\npackage and their cross-dependency pins in a single step.\n\nIf preflight reports a pin problem, stop: see the pin notes in Step 2.\n\n---\n\n## Step 4: Dry run\n\nA dry run builds and stages the artifacts in the Exit Gate Artifact Registry,\nremoves them again, and pushes nothing.\n\n```bash\ngh workflow run release-pypi.yml --repo a2ui-project/a2ui --ref main \\\n -f package=\"${PACKAGE}\" -f bump=\"${BUMP}\" -f dry_run=true\n```\n\nWait a few seconds, then find the run and watch it:\n\n```bash\ngh run list --repo a2ui-project/a2ui --workflow=release-pypi.yml --limit 1 \\\n --json databaseId,status,url\ngh run watch \"${RUN_ID}\" --repo a2ui-project/a2ui --exit-status\n```\n\n> [!TIP]\n> Use the full `databaseId`. A truncated run ID returns 404.\n\nIf it fails, read the failing step's log and consult Troubleshooting below\nbefore retrying.\n\nWhen it passes, read back the plan the run actually computed. The dry run does\nnot upload the plan artifact, and step summaries are not available over the API,\nbut the plan step prints the JSON into the log:\n\n```bash\ngh run view \"${RUN_ID}\" --repo a2ui-project/a2ui --log \\\n | grep -A 20 'Build the release plan'\n```\n\nCompare it against the local `plan` output from Step 2. They are computed the\nsame way and should agree. If they differ, a tag landed in between — stop and\nwork out why before going any further.\n\n---\n\n## Step 5: Confirm with the maintainer\n\n**Stop here.** Show the maintainer:\n\n- the exact versions and tags from the dry run's plan,\n- the changelog entries that will become the release notes,\n- that the dry run passed.\n\nQuote the version numbers in full, for example `a2ui-agent-sdk 0.7.0`. Do not\ndescribe the release only as \"a minor bump\" — the bump level is the input, the\nversion is the irreversible consequence, and it is the version the maintainer\nneeds to approve.\n\nThen ask for explicit confirmation to publish. Proceed only on a clear yes.\n\n---\n\n## Step 6: Publish\n\n```bash\nAUTHOR_NAME=$(git config user.name)\nAUTHOR_EMAIL=$(git config user.email)\ngh workflow run release-pypi.yml --repo a2ui-project/a2ui --ref main \\\n -f package=\"${PACKAGE}\" -f bump=\"${BUMP}\" -f dry_run=false \\\n -f author_name=\"${AUTHOR_NAME}\" -f author_email=\"${AUTHOR_EMAIL}\"\n```\n\nWatch it as in Step 4. The run pushes the tags, stages the artifacts, uploads\nthe manifest that triggers the Exit Gate, and creates the GitHub releases.\n\nFour jobs follow:\n\n| Job | What it does | If it fails |\n| :---------- | :----------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------- |\n| `build` | Runs tests and builds distributions | Test failure or malformed distribution. See Troubleshooting. |\n| `release` | Stages, tags, and triggers publishing | Real failure. See Troubleshooting. |\n| `confirm` | Polls PyPI, then links the GitHub releases | A timeout is not a failure. The hourly [Confirm PyPI publication](../../../.github/workflows/release-verify-pypi.yml) workflow finishes the job. |\n| `changelog` | Pushes the changelog branch | Publishing already succeeded. Cut the changelog by hand and open the PR yourself. |\n\n> [!IMPORTANT]\n> **The run stays active for several minutes after `release` goes green, and\n> that is normal.** Triggering the Exit Gate is not publishing. The Exit Gate\n> works asynchronously and reports only by email, so the `confirm` job sits and\n> polls PyPI every 30 seconds for up to 20 minutes waiting for the version to\n> appear.\n>\n> `gh run watch` blocks until all three jobs finish, so it is the wait. Let it\n> run. Do not poll PyPI in a loop alongside it, and do not report the release as\n> finished — or as failed — while `confirm` is still in progress.\n\n---\n\n## Step 7: Follow through\n\nA release is not done when the workflow goes green.\n\n1. **Confirm the version is live.** The waiting has already happened on the\n runner, so read the `confirm` job's outcome rather than starting a fresh\n wait:\n\n - **`confirm` succeeded** — the version is on PyPI and the GitHub releases\n have been updated with links. Verify once and move on:\n\n ```bash\n curl -s -o /dev/null -w '%{http_code}\\n' \"https://pypi.org/pypi/${PYPI_NAME}/${VERSION}/json\"\n ```\n\n `200` confirms it. A `404` here, after `confirm` reported success, is a CDN\n lag of a minute or two — wait briefly and check again.\n\n - **`confirm` timed out** — publishing took longer than 20 minutes. **This is\n not a failed release.** The artifacts are staged and the Exit Gate still\n has them. Do not re-run the release, and do not try to publish the version\n again: that would burn a version number. Tell the maintainer it is\n outstanding, and leave it to the hourly\n [Confirm PyPI publication](../../../.github/workflows/release-verify-pypi.yml)\n workflow, which finds the release by its pending marker and links it once\n PyPI catches up. The Exit Gate also emails\n `a2ui-core-working-group@google.com` with the outcome either way.\n\n - **`confirm` failed for another reason** — read the log. The publish itself\n may still have succeeded, so check PyPI before concluding anything.\n\n2. **Open the changelog pull request and get it merged.** The release pushed the\n branch but deliberately did not open the pull request — see \"What runs\n where\". Open it yourself:\n\n ```bash\n BRANCH=$(git ls-remote --heads \"${REMOTE}\" 'release/changelog-*' \\\n | sed 's#.*refs/heads/##')\n gh pr create --repo a2ui-project/a2ui --base main --head \"$BRANCH\" \\\n --title \"chore(release): changelog for ${RELEASED}\" \\\n --body \"Moves the \\`## Unreleased\\` entries under the released versions.\"\n ```\n\n Check the diff touches only `CHANGELOG.md` files, then ask the maintainer to\n review it. Do not leave it open: Step 3 blocks the next release until the\n branch is gone.\n\n3. **Report** the published versions, the GitHub release links, and the\n changelog pull request link.\n\n---\n\n## Troubleshooting\n\n**`could not find any workflows named release-pypi.yml`** — the workflow is only\ndispatchable once it is on `main`. Check it has merged.\n\n**HTTP 403 from Artifact Registry** — the Exit Gate allowlists\n`a2ui-project/a2ui` only. This is the expected result on a fork, and not a bug.\nOn the real repository it means the builder identity no longer matches; see\n`go/oss-exit-gate-builders`.\n\n**`Permission denied` or a failed OIDC exchange** — the Exit Gate matches the\nworkflow path and branch exactly:\n\n```\ngithub_workflow:a2ui-project/a2ui/.github/workflows/release-pypi.yml@refs/heads/main\n```\n\nRenaming or moving the workflow file breaks releases until the internal config\nis updated. It also cannot be triggered from a branch or a tag, only `main`.\n\n**`... is already on PyPI`** — the version was published previously. It cannot be\nrepublished. Work out why the tag series and PyPI disagree before retrying.\n\n**`One or more packages are not in the project's allowlist` or `400 Non-user identities cannot create new projects` in Exit Gate logs**: a brand-new package name must be added to the OSS Exit Gate allowlist and registered as a Pending Publisher on `https://pypi.org/manage/account/publishing/` before its first release. Because PyPI allows only one Pending Publisher at a time for `a2ui-py@oss-exit-gate-prod.iam.gserviceaccount.com`, publish brand-new packages one at a time. See [docs/contributing/release.md](../../../docs/contributing/release.md#releasing-a-new-package-for-the-first-time) and `go/a2ui-release#pypi`.\n\n**A dry run or failed staging left artifacts behind** — the cleanup step runs\neven on partial failure, but if it was itself skipped, remove the staged version\nby hand:\n\n```bash\ngcloud artifacts versions delete \"${VERSION}\" --package=\"${PYPI_NAME}\" \\\n --repository=a2ui--pypi --location=us --project=oss-exit-gate-prod --quiet\n```\n\n---\n\n## Rules\n\n- Never edit a version by hand. Versions come from git tags via `hatch-vcs`, and\n the workflow verifies the built artifacts against the version it planned.\n- Never push tags or run the release scripts locally to publish. The scripts\n under `.github/scripts/` are safe to run read-only for `notes`, `next`,\n `current`, `tag`, and `check`. Everything else belongs to the workflow.\n- Never dispatch `dry_run: false` without the Step 5 confirmation.\n- If the maintainer asks to skip the dry run, push back once: it is the only\n rehearsal before an irreversible publish. Defer if they insist.\n\n\n# References Skill\n\nPath: `.agents/skills/a2ui-remediate-problem/references/pr-description-template.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/a2ui-remediate-problem/references/pr-description-template.md)\n\n\n---\nname: a2ui-remediate-problem\ndescription: Remediates a specific recommendation from an A2UI compliance report issue, or resolves any general GitHub issue, by inspecting context, implementing minimal targeted fixes, verifying tests, creating a branch, and opening a developer-signed Pull Request. Use when asked to fix or remediate an A2UI compliance audit finding, recommendation, or repository issue.\n---\n\n# A2UI Issue & Compliance Remediation Skill\n\nThis skill guides an AI coding agent or engineer on how to remediate a specific recommendation from an A2UI compliance report or resolve any general repository issue and submit a clean, developer-signed Pull Request.\n\n---\n\n## **Workflow**\n\nFollow these steps to remediate an issue:\n\n### Step 1: Identify & Read Issue Context\n\n1. **Determine the Target Issue**:\n - If the user provided an issue number or URL in their request, extract `ISSUE_NUMBER`.\n - If no issue was specified, ask the user (prefer using the `ask_question` tool):\n _\"Which GitHub issue would you like to remediate? (Please provide the issue number or URL, e.g. 2391)\"_\n\n2. **Retrieve Context & Determine Issue Type**:\n - Run the helper script to inspect the issue:\n ```bash\n python3 .agents/skills/a2ui-remediate-problem/scripts/extract_recommendation.py \"${ISSUE_NUMBER}\" [RECOMMENDATION_INDEX] --json\n ```\n - **Scenario A: Compliance Report with Multiple Recommendations**:\n - If a recommendation index was provided (e.g. `2`), the script extracts that item's details and priority.\n - If no recommendation index was specified, the script outputs all available recommendations in the issue. Ask the user (via `ask_question`) which recommendation item they would like to address.\n - Review the surrounding audit sections in the report (such as `## Codebase Blueprint Compliance Audit`, `## Code & Documentation Sync Audit`, or `## Test Quality & Assertions Audit`) for detailed findings.\n - **Scenario B: General Issue (Bug Report, Feature Request, or Non-Audit Issue)**:\n - If the issue is not a compliance report, the script returns the issue title and body as the problem statement to remediate.\n\n---\n\n### Step 2: Formulate & Apply Remediation\n\n1. Identify the files and codebases referenced by the issue or recommendation.\n2. Carefully inspect the current source code, documentation, or blueprint files.\n3. Implement the minimal necessary change to remediate the reported problem.\n - **CRITICAL RULE**: Do not make unrelated changes, refactorings, or formatting edits outside the scope of the target issue or recommendation.\n4. Format modified files and ensure code style compliance:\n ```bash\n ./scripts/fix_format.sh\n ```\n5. If modifying tests or scripts, execute local tests across the affected packages to ensure no regressions were introduced.\n\n---\n\n### Step 3: Choose Destination & Create Workspace / Branch\n\n1. Check with the user on where they would like the changes created and what branch name to use (prefer using the `ask_question` tool or equivalent interactive tool if available):\n - **Recommended branch name**: `remediation/issue-${ISSUE_NUMBER}-${RECOMMENDATION_INDEX}` (or `remediation/issue-${ISSUE_NUMBER}` for general issues).\n - Let the user choose whether to create a separate git worktree (using their preferred local worktree conventions), checkout a new branch in the current directory, or apply changes in place.\n2. Note the chosen branch name in `BRANCH_NAME`.\n3. Ensure the working tree is clean and up to date with `upstream/main`.\n\n---\n\n### Step 4: Commit Changes\n\n1. Stage all modified files relevant to the remediation:\n ```bash\n git add -u\n ```\n2. Create a conventional commit referencing the issue number:\n - For compliance recommendations:\n ```bash\n git commit -m \"fix(compliance): remediate issue #${ISSUE_NUMBER} recommendation ${RECOMMENDATION_INDEX}\"\n ```\n - For general issues:\n ```bash\n git commit -m \"fix(scope): remediate issue #${ISSUE_NUMBER} - ${CONCISE_SUMMARY}\"\n ```\n\n---\n\n### Step 5: Create Pull Request & Notify Issue (Optional / Upon Request)\n\n1. Check with the user whether they would like to submit a Pull Request (prefer using the `ask_question` tool or equivalent interactive tool if available):\n - **Recommended default**: Submit as a Draft PR (`--draft`) so CI checks run while allowing final review before requesting maintainer approvals.\n - Alternatively, submit directly as ready for review, or skip PR creation if the user wants to inspect changes locally first.\n2. If submitting a PR, generate a clear, descriptive PR title following Conventional Commits that concisely explains the specific fix being made (e.g. `fix(swift): create missing top-level README in swift/core`). **Do NOT include generic issue or recommendation numbers in the PR title.**\n3. Draft the PR description into a temporary file `pr_description.md` following [pr-description-template.md](references/pr-description-template.md).\n4. Push the branch to `origin` (or user's fork) and create the Pull Request against `main`:\n ```bash\n git push -u origin \"${BRANCH_NAME}\"\n PR_URL=$(gh pr create --draft \\\n --repo a2ui-project/a2ui \\\n --head \"${BRANCH_NAME}\" \\\n --base main \\\n --title \"${PR_TITLE}\" \\\n --body-file pr_description.md)\n ```\n _(Note: Omit `--draft` if the user prefers an immediate ready-for-review PR. If pushing from a fork, `gh pr create` automatically resolves the fork's head branch or accepts `--head :${BRANCH_NAME}`.)_\n5. Clean up the temporary file `pr_description.md`.\n6. Comment on the original issue to notify maintainers of the new PR:\n ```bash\n gh issue comment \"${ISSUE_NUMBER}\" \\\n --repo a2ui-project/a2ui \\\n --body \"🤖 Automated remediation triggered! Created PR (${PR_URL}) on branch \\`${BRANCH_NAME}\\` to address recommendation ${RECOMMENDATION_INDEX}.\"\n ```\n\n---\n\n## **References**\n\n- Refer to the [PR description template](references/pr-description-template.md) for PR body structure and guidelines.\n- Refer to the [`gh-reference`](../a2ui-audit/references/gh-reference.md) for GitHub CLI commands.\n\n\n---\nname: a2ui-test-quality-check\ndescription: Auditing test suites for assertion utility, boundary cases coverage, and verification strength.\n---\n\n# A2UI Test Quality & Assertions Auditing Skill\n\nThis skill guides you through the process of auditing codebase test suites to verify that tests are providing robust, meaningful assertions and verifying critical invariants, rather than simply running paths for code coverage.\n\n---\n\n## **Instructions**\n\n1. **Locate Test Suites**:\n - Find all test directories and test files in each platform's implementation folder (e.g. `tests/`, `test/`, `*Tests.swift`).\n\n2. **Audit Assertion Quality**:\n - For each test case, inspect the assertions used:\n - Flag \"weak assertions\" that only verify non-null or truthy values without checking specific payload structure, field values, or types (e.g. `expect(result).not.toBeNull()` on a complex object).\n - Flag \"empty tests\" that execute code blocks but lack any assertions or mocks verifications (e.g. executing to check for lack of exceptions, unless it is explicitly marked as a no-throw smoke test).\n - Ensure that return models, state side effects, and events dispatched have corresponding value-matching assertions.\n\n3. **Audit Behavioral and Boundary Coverage**:\n - Review if tests exist for typical logical edge cases:\n - Null, empty, or overflow values.\n - Invalid JSON or parsing errors (e.g., throwing correct exceptions).\n - Exception propagation and error boundaries.\n - Timeout handling and cleanup side effects.\n - Look for cases where tests might pass when they should fail.\n - Cross-reference with the codebase's main files: if a file has complex parsing/validation code, ensure there are dedicated failing test cases asserting that errors are reported correctly.\n\n4. **Audit Mocking Realism**:\n - Ensure mocks and stubs verify their call parameters (e.g., verifying that a mock transport received the exact payload sent by the SDK, rather than just asserting it was called).\n\n5. **Format the Report**:\n - Build a Markdown report summarizing the findings:\n - Table of audited test suites and files.\n - **Weak Assertions**: List of test cases that rely on weak or missing assertions.\n - **Missing Edge Case Tests**: Critical logic boundaries and exception paths lacking tests.\n - **Mocking Mismatches**: Mock implementations that fail to verify call structures.\n - Return this Markdown report as your final response.\n\n\n---\nname: coding-principles\ndescription: >-\n Enforces engineering, architecture, public API, and code quality standards distilled from human\n reviewer feedback across A2UI pull requests. Use when authoring new code, refactoring, addressing\n review feedback, or reviewing PR diffs. Don't use for release publishing or spec blueprint\n generation without code or PR changes.\n---\n\n# Skill: coding-principles\n\n**Purpose**: Core engineering, architecture, and code quality standards established by human reviewers across A2UI pull requests. Used by agents when authoring changes, refactoring code, addressing review feedback, or reviewing pull request diffs to maintain repository health across all languages.\n\n---\n\n## Specification and Blueprint Grounding\n\nBefore modifying or implementing code in any language, consult the authoritative specifications and blueprints:\n\n- **Protocol JSON Schemas**: [`specification/v0_9_1/json/`](../../../specification/v0_9_1/json/) and [`specification/v1_0/json/`](../../../specification/v1_0/json/) define wire-format envelopes, types, and validation constraints.\n- **Component Catalogs**: [`catalogs/basic/v1/catalog.json`](../../../catalogs/basic/v1/catalog.json) defines standard components, properties, and function signatures.\n- **Core Module Blueprint**: [`a2ui_core.blueprint.md`](../../../blueprints/modules/a2ui_core.blueprint.md) specifies state containers (`DataModel`, `SurfaceModel`), `MessageProcessor`, JSON pointer rules, auto-vivification, and error semantics.\n- **Agent SDK Blueprint**: [`a2ui_agent.blueprint.md`](../../../blueprints/modules/a2ui_agent.blueprint.md) specifies `A2uiGenerator`, `A2uiRequestProcessor`, inference format strategies, and prompt generation.\n- **Framework Adapter Blueprint**: [`a2ui_framework_adapter.blueprint.md`](../../../blueprints/modules/a2ui_framework_adapter.blueprint.md) specifies view mapping, reactive subscription lifecycles, and layout behavior.\n- **Typesafe Builder Blueprint**: [`typesafe_builder_api.blueprint.md`](../../../blueprints/features/typesafe_builder_api.blueprint.md) specifies fluent builder hierarchies.\n- **Reference Implementation**: [`typescript/core/web_core/`](../../../typescript/core/web_core/) serves as the canonical behavioral reference for edge-case resolution.\n\n---\n\n## Progressive Discoverability: Two-Level Subskill Routing\n\nBecause the A2UI repository spans multiple languages (`typescript/`, `python/`, `dart/`, `swift/`) and shared specifications (`specification/`, `catalogs/`), agents must use a two-level progressive discovery workflow:\n\n1. **Level 1 (Cross-Language Subskills)**: Activate language-agnostic principles that govern pull request scope, software design, public API boundaries, specification immutability, and changelogs across the entire monorepo.\n2. **Level 2 (Language-Specific Routing)**: Route by the programming languages modified in the diff to load only the subskills and language guides relevant to those languages.\n\n### Step 1: Inspect the PR Diff\n\nReview the modified files and categories of changes:\n\n```bash\n# In an active branch:\ngit diff main --stat\n```\n\nIdentify both:\n\n- **Cross-cutting functional areas** impacted (public exports, specifications, catalogs, changelogs, PR structure).\n- **Programming languages and directories** touched (`typescript/`, `python/`, `dart/`, `swift/`, `samples/`, `tools/`).\n\n---\n\n### Step 2: Activate Cross-Language Subskills (Language-Agnostic)\n\nEvaluate the cross-language subskills below against the diff and read any activated document in full:\n\n#### 1. PR Hygiene, Atomicity, Scope Control & Software Design\n\n- **Skill**: [`pr-hygiene`](../pr-hygiene/SKILL.md)\n- **Activate if**: Always applicable when authoring, preparing, or reviewing a pull request.\n\n#### 2. Public API Boundaries, Cross-Framework Design & Changelogs\n\n- **Document**: [`subskills/public-api-and-cross-framework-design.md`](subskills/public-api-and-cross-framework-design.md)\n- **Activate if**:\n - Any package entrypoint or facade (`index.ts`, `public-api.ts`, `package.json`, `__init__.py`, `lib/*.dart`, or public Swift API), or any `CHANGELOG.md` is modified.\n - Any new class, function, interface, type, model, or DI token is exported.\n - Renderer APIs, registration helpers, or adapters across `@a2ui/angular`, `@a2ui/lit`, `@a2ui/react`, `a2ui_flutter`, or `A2UISwiftUI` are modified.\n - Imports between sibling packages change.\n - Files under `specification/` or `catalogs/` (schemas, catalog fixtures, or examples) are modified or added.\n - Breaking changes or public API deprecations are introduced.\n - A new source file is added (verify it has a single responsibility rather than acting as a catch-all `types.*` or `utils.*` file).\n\n#### 3. Updating Changelogs (`CHANGELOG.md`)\n\n- **Skill**: [`update-changelog`](../update-changelog/SKILL.md)\n- **Activate if**: Any `CHANGELOG.md` is modified or a published package's public API or consumer-observable behavior changes.\n\n---\n\n### Step 3: Route by Language for Language-Dependent Principles\n\nInspect the file extensions and directories in `git diff main --stat` and follow the matching language route(s) below. Only load routers and guides for languages present in your diff:\n\n| Language / Ecosystem | Matching Paths & Extensions | Progressive Discovery Target |\n| :-------------------------------------------------------------- | :--------------------------------------------------------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| **TypeScript & Web** (Lit, Angular, React, Web Core, CSS, HTML) | `*.ts`, `*.tsx`, `*.css`, `typescript/`, `samples/client/{lit,angular,react}/`, `tools/` | Read the TypeScript & Web router: [`subskills/typescript/INDEX.md`](subskills/typescript/INDEX.md) to activate specific TypeScript, reactive lifecycle, CSS theming, accessibility, DOM testing, and AST public API subskills. |\n| **Python** (Core, Agent SDK, Builders, Evaluators, Scripts) | `*.py`, `python/`, `eval/`, `samples/agent/`, `tools/`, `scripts/` | Read the Python router: [`subskills/python/INDEX.md`](subskills/python/INDEX.md) to activate Python package architecture, facade conventions, typing, and verification subskills. |\n| **Swift & SwiftUI** (Core, SwiftUI Adapter, iOS Sample) | `*.swift`, `swift/`, `Package.swift` | Read the Swift & SwiftUI router: [`subskills/swift/INDEX.md`](subskills/swift/INDEX.md) to activate Swift target architecture, coding standards, and `Testing` subskills. |\n| **Dart & Flutter** (Core, Agent SDK, Flutter Adapter) | `*.dart`, `dart/`, `samples/client/flutter/`, `pubspec.yaml` | Read the Dart & Flutter router: [`subskills/dart/INDEX.md`](subskills/dart/INDEX.md) to activate Dart analyzer rules, package versioning, and changelog subskills. |\n\n---\n\n### Step 4: Progressively Load Activated Subskills\n\nRead only the cross-language subskills activated in Step 2 and the language-specific subskills selected through Step 3 to evaluate your code against their rationales, checklists, and examples without loading unrelated language rules into context.\n\n\n# Dart Skill\n\nPath: `.agents/skills/coding-principles/subskills/dart/INDEX.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/dart/INDEX.md)\n\n\n# Dart Skill\n\nPath: `.agents/skills/coding-principles/subskills/dart/versioning-and-releases.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/dart/versioning-and-releases.md)\n\n\n# Subskills Skill\n\nPath: `.agents/skills/coding-principles/subskills/public-api-and-cross-framework-design.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/public-api-and-cross-framework-design.md)\n\n\n# Python Skill\n\nPath: `.agents/skills/coding-principles/subskills/python/architecture-and-facades.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/python/architecture-and-facades.md)\n\n\n# Python Skill\n\nPath: `.agents/skills/coding-principles/subskills/python/coding-standards-and-verification.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/python/coding-standards-and-verification.md)\n\n\n# Python Skill\n\nPath: `.agents/skills/coding-principles/subskills/python/INDEX.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/python/INDEX.md)\n\n\n# Swift Skill\n\nPath: `.agents/skills/coding-principles/subskills/swift/coding-standards-and-testing.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/swift/coding-standards-and-testing.md)\n\n\n# Swift Skill\n\nPath: `.agents/skills/coding-principles/subskills/swift/INDEX.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/swift/INDEX.md)\n\n\n# Typescript Skill\n\nPath: `.agents/skills/coding-principles/subskills/typescript/accessibility-semantics.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/accessibility-semantics.md)\n\n\n# Typescript Skill\n\nPath: `.agents/skills/coding-principles/subskills/typescript/css-theming-styling.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/css-theming-styling.md)\n\n\n# Typescript Skill\n\nPath: `.agents/skills/coding-principles/subskills/typescript/INDEX.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/INDEX.md)\n\n\n# Typescript Skill\n\nPath: `.agents/skills/coding-principles/subskills/typescript/reactive-lifecycle-performance.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/reactive-lifecycle-performance.md)\n\n\n# References Skill\n\nPath: `.agents/skills/coding-principles/subskills/typescript/references/inspecting-typescript-public-api.md`\n\n[View Raw Content on GitHub](https://raw.githubusercontent.com/a2ui-project/a2ui/HEAD/.agents/skills/coding-principles/subskills/typescript/references/inspecting-typescript-public-api.md)\n\n\n"}