Adding AI harness with agent definitions, skills, and rules

.gitignore

@@ -7,3 +7,4 @@
 /captures
 .externalNativeBuild
 **/*.swp
+/.agents/

AGENTS.md

@@ -0,0 +1,60 @@
+# AI Agent Harness for Android Browser Helper
+
+This page defines the rules, skills, and prompts for AI agents working on this project.
+
+## Rule Inheritance
+
+This harness inherits from:
+- [common.md](_agents/prompts/common.md)
+
+## Common Directives
+
+Instructions that are useful for Android Browser Helper development.
+
+### Paths
+
+* All files in the project's source can be read relative to the workspace root.
+
+### Building
+
+* Do not attempt a build without first establishing the correct target.
+* Build the project using Gradle:
+  * To build the entire project: `./gradlew build`
+  * To build a specific module (e.g., `androidbrowserhelper`): `./gradlew :androidbrowserhelper:assembleDebug`
+
+### Testing
+
+* Run tests using Gradle:
+  * To run all unit tests: `./gradlew test`
+  * To run unit tests for a specific module: `./gradlew :androidbrowserhelper:test`
+  * To run instrumentation tests (if emulator is available): `./gradlew connectedAndroidTest`
+
+### Coding
+
+* Stay on task: Do not address code health issues or TODOs in code unless it is required to achieve your given task.
+* Add code comments sparingly: Focus on *why* something is done, not *what* is done.
+* **Documentation**: Keep documentation fresh. Update Javadoc for public API changes, and update relevant markdown files (e.g., `README.md`, `docs/`) when changing behavior or APIs.
+
+### Git Operations
+
+* **Always branched:** Ensure you are not on the `main` branch if you are making commits. If you are, first do `git checkout -b {BRANCH_NAME}`.
+* **Commit messages:**
+  * Use active voice and avoid passive voice.
+  * Use present tense or imperative mood (e.g., "Change foo" instead of "Changed foo").
+  * Wrap the commit message at 72 characters when possible.
+
+---
+
+## Canonical Documentation
+
+- [README.md](README.md)
+- [docs/](docs/)
+
+## Project Rules
+
+Refer to the specific rules in `_agents/rules/`:
+- [CODE_STRUCTURE.md](_agents/rules/CODE_STRUCTURE.md)
+- [DEPENDENCIES.md](_agents/rules/DEPENDENCIES.md)
+- [STYLE.md](_agents/rules/STYLE.md)
+- [TESTING.md](_agents/rules/TESTING.md)
+- [REVIEWS.md](_agents/rules/REVIEWS.md)

_agents/INDEX.md

@@ -0,0 +1,25 @@
+# AI Agent Harness Catalog
+
+This directory contains the configuration, rules, and skills for AI agents working in this repository.
+
+## Directory Structure
+
+*   **[prompts/](prompts/)**: Common system prompts and workflow templates.
+    *   [`common.md`](prompts/common.md): Standard edit/fix workflow guidelines.
+*   **[rules/](rules/)**: Domain-specific coding and testing rules.
+    *   [`CODE_STRUCTURE.md`](rules/CODE_STRUCTURE.md): Gradle modules and key classes.
+    *   [`DEPENDENCIES.md`](rules/DEPENDENCIES.md): Dependency policies (small APK size, Java-only).
+    *   [`STYLE.md`](rules/STYLE.md): Google Java Style and copyright requirements.
+    *   [`TESTING.md`](rules/TESTING.md): Robolectric, Instrumentation, and manual TWA testing steps.
+    *   [`REVIEWS.md`](rules/REVIEWS.md): Code review checklist.
+*   **[skills/](skills/)**: Custom agent workflows.
+    *   [`doc-writer/`](skills/doc-writer/): GAN-based design and execution plan authoring.
+*   **[templates/](templates/)**: Templates for documents generated by skills.
+    *   [`designs.md`](templates/designs.md): Technical Design Document template.
+    *   [`plans.md`](templates/plans.md): Execution Plan template.
+*   **[designs/](designs/)**: Output directory for generated Technical Design Documents.
+    *   [`index.md`](designs/index.md): Index registry for designs.
+*   **[plans/](plans/)**: Output directory for generated Execution Plans.
+    *   [`index.md`](plans/index.md): Index registry for plans.
+*   **[`skills.json`](skills.json)**: Project skills registry.
+*   **[`agents.json`](agents.json)**: Project subagents registry.

_agents/RULES.md

@@ -0,0 +1,12 @@
+# Agent Rules Routing Table
+
+Use this table to quickly find the relevant rules for your task.
+
+| If you are... | Refer to... | Description |
+| :--- | :--- | :--- |
+| **Exploring the codebase** | [`rules/CODE_STRUCTURE.md`](rules/CODE_STRUCTURE.md) | Maps Gradle modules and key entry-point classes. |
+| **Writing or editing Java code** | [`rules/STYLE.md`](rules/STYLE.md) | Coding style (Google Java Style) and copyright headers. |
+| **Adding or modifying dependencies** | [`rules/DEPENDENCIES.md`](rules/DEPENDENCIES.md) | Constraints on external libraries and Kotlin usage. |
+| **Writing, running, or debugging tests** | [`rules/TESTING.md`](rules/TESTING.md) | Robolectric unit tests, Instrumentation tests, and TWA manual debugging (DAL bypass, Logcat). |
+| **Reviewing code or designs** | [`rules/REVIEWS.md`](rules/REVIEWS.md) | Checklist for security, compatibility, and performance. |
+| **Executing a task** | [`prompts/common.md`](prompts/common.md) | Standard Edit/Fix workflow guidelines. |

_agents/agents.json

@@ -0,0 +1,13 @@
+{
+  "entries": [
+    {
+      "path": "_agents/agents/design_reviewer"
+    },
+    {
+      "path": "_agents/agents/reviewer"
+    },
+    {
+      "path": "_agents/agents/android-browser-helper_agent"
+    }
+  ]
+}

_agents/agents/android-browser-helper_agent/agent.json

@@ -0,0 +1,7 @@
+{
+  "name": "android-browser-helper_agent",
+  "description": "Specialized Agent for the Android Browser Helper project, tailored for Custom Tabs and TWA integrations.",
+  "configPath": {
+    "relativePathToConfig": "config.yaml"
+  }
+}

_agents/agents/android-browser-helper_agent/config.yaml

@@ -0,0 +1,13 @@
+coding_agent:
+  agentic_mode: true
+
+prompt_section_customization:
+  add_prompt_sections:
+    - prompt_section:
+        title: "Android Browser Helper Project Directives"
+        content: |
+          You are the Android Browser Helper agent. Your goal is to assist with workspace development in this repository.
+          You MUST ALWAYS consult the setup, rules, and routing in `@/AGENTS.md` first.
+          You also have access to a project-specific skill `harness`. You should use it to load project context and handle project-specific operations.
+          When invoking skills like `doc-writer`, infer the required parameters dynamically by inspecting the workspace structure (e.g., placing designs in `_agents/designs/` and plans in `_agents/plans/`) rather than asking the user to specify them directly.
+      insert_before_section: artifacts

_agents/agents/design_reviewer/agent.json

@@ -0,0 +1,7 @@
+{
+  "name": "adversarial_reviewer",
+  "description": "Specialized staff-level architect subagent that performs Skeptical Adversarial Design and Code Reviews following agents/rules/REVIEWS.md guidelines.",
+  "configPath": {
+    "relativePathToConfig": "config.yaml"
+  }
+}

_agents/agents/design_reviewer/config.yaml

@@ -0,0 +1,29 @@
+coding_agent:
+  agentic_mode: true
+
+prompt_section_customization:
+  add_prompt_sections:
+    - prompt_section:
+        title: "Core Mandates"
+        content: |
+          # Core Mandates (Universal Subagent Context)
+          You are a specialized subagent operating within the Jetski ecosystem. You have been delegated a specific task by the Orchestrator.
+          1. Security & System Integrity: Never log, print, or commit secrets, API keys, or credentials.
+          2. Context Efficiency: Combined search and read turns are highly preferred. Use grep_search or find_by_name before reading entire files.
+          3. No Chitchat: Focus purely on intent, findings, and technical rationale. Do not narrate tool usage.
+          4. Read-Only Protocol: You are a strictly read-only agent. You are forbidden from using any tools to modify files or configurations in this codebase.
+          5. Messaging Protocol: ALWAYS return your final review report via the send_message tool to the Orchestrator's ID (the conversation ID that invoked you).
+      insert_before_section: "artifacts"
+
+    - prompt_section:
+        title: "Role: The Skeptical Architect"
+        content: |
+          # Role: The Skeptical Architect
+          You are the **Design Reviewer** subagent, a senior staff-level architect focused on identifying hidden assumptions, architectural risks, and mismatches.
+          Your primary mandate is to flawlessly execute the standard design review operating procedure.
+
+          Before proceeding, you MUST execute the `design-review` skill by reading its instructions at:
+          `_agents/skills/design-review/SKILL.md`
+
+          You must strictly abide by grading rubrics, checks, and output formatting defined in that skill.
+      insert_after_section: "Core Mandates"

_agents/agents/reviewer/agent.json

@@ -0,0 +1,7 @@
+{
+  "name": "reviewer",
+  "description": "Senior SWE subagent for identifying code issues, enforcing Android/Java standards, and producing Dashboard-First code review reports.",
+  "configPath": {
+    "relativePathToConfig": "config.yaml"
+  }
+}

_agents/agents/reviewer/config.yaml

@@ -0,0 +1,27 @@
+coding_agent:
+  agentic_mode: true
+
+prompt_section_customization:
+  add_prompt_sections:
+    - prompt_section:
+        title: "Core Mandates"
+        content: |
+          # Core Mandates (Universal Subagent Context)
+          You are a specialized code review subagent operating within the Jetski ecosystem. You have been delegated a code review task by the Orchestrator.
+          1. Security & System Integrity: Never log, print, or commit secrets, API keys, or credentials.
+          2. Read-Only Protocol: You are a strictly read-only agent. You are forbidden from using any tools to modify files or configurations in this codebase.
+          3. Messaging Protocol: ALWAYS return your final review report via the send_message tool to the Orchestrator's ID.
+      insert_before_section: "artifacts"
+
+    - prompt_section:
+        title: "Role: Senior Staff SWE Reviewer"
+        content: |
+          # Role: Senior Staff SWE Reviewer
+          You are a Senior Staff Software Engineer reviewing code changes for the `android-browser-helper` project.
+          Your primary mandate is to flawlessly execute the standard code review operating procedure.
+
+          Before proceeding, you MUST execute the `code-review` skill by reading its instructions at:
+          `_agents/skills/code-review/SKILL.md`
+
+          You must strictly abide by grading rubrics, verification checklists, and especially the **Dashboard-First Report Format** defined in that skill.
+      insert_after_section: "Core Mandates"

_agents/designs/index.md

@@ -0,0 +1,7 @@
+# Design Documents Index
+
+This file tracks all Technical Design Documents created for the Android Browser Helper project.
+
+| ID | Title | Status | Date | Bug | Parent Plan |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| | | | | | |

_agents/plans/index.md

@@ -0,0 +1,7 @@
+# Execution Plans Index
+
+This file tracks all Execution Plans created for the Android Browser Helper project.
+
+| ID | Title | Status | Date | Design Doc | Bug |
+| :--- | :--- | :--- | :--- | :--- | :--- |
+| | | | | | |

_agents/prompts/common.md

@@ -0,0 +1,40 @@
+# Workflow Tips
+
+## General Workflow:
+
+  * **User Guidance:** Proactively communicate your plan and the reason for each step.
+  * **File Creation Pre-check:** Before creating any new file, you MUST first perform a thorough search for existing files that can be modified or extended. This is especially critical for tests; never create a new test file if one already exists for the component in question. Always add new tests to the existing test file.
+  * **Read Before Write/Edit:** **ALWAYS** read the entire file content immediately before writing or editing.
+
+## Standard Edit/Fix Workflow:
+
+**IMPORTANT:** This workflow takes precedence over all other coding instructions. Read and follow everything strictly without skipping steps whenever code editing is involved. Any skipping requires a proactive message to the user about the reason to skip.
+
+0.  **Git Branching (MANDATORY PRE-REQUISITE):** Before making any code changes, ensure you are on an appropriate branch (not `main`). Refer to [AGENTS.md](../../AGENTS.md) for git constraints.
+
+1.  **Comprehensive Code and Task Understanding (MANDATORY FIRST STEP):** Before writing or modifying any code, you MUST perform the following analysis to ensure comprehensive understanding of the relevant code and the task. This is a non-negotiable prerequisite for all coding tasks.
+      * **a. Identify the Core Files:** Locate the files that are most relevant to the user's request. All analysis starts from these files.
+      * **b. Conduct a Full Audit:**
+        i. Read the full source of **EVERY** core file.
+        ii. For each core file, summarize the control flow and ownership semantics. State the intended purpose of the core file.
+      * **c. State Your Understanding:** After completing the audit, you should briefly state the core files you have reviewed, confirming your understanding of the data flow and component interactions before proposing a plan.
+      * **d. Anti-Patterns to AVOID:**
+          * **NEVER** assume the behavior of a function or class from its name or from usage in other files. **ALWAYS** read the source implementation.
+          * **ALWAYS** check at least one call-site for a function or class to understand its usage. The context is as important as the implementation.
+2.  **Make Change:** After a comprehensive code and task understanding, apply the edit or write the file.
+      * When making code edits, focus **ONLY** on code edits that directly solve the task prompted by the user.
+3.  **Write/Update Tests:**
+      * First, search for existing tests related to the modified code and update them as needed to reflect the changes.
+      * If no relevant tests exist, write new unit tests or integration tests if it's reasonable and beneficial for the change made.
+      * If tests are deemed not applicable for a specific change (e.g., a trivial comment update), explicitly state this and the reason why before moving to the next step.
+4.  **Build:** **ALWAYS** build relevant targets after making edits.
+5.  **Fix compile errors:** **ALWAYS** follow these steps to fix compile errors.
+      * **ALWAYS** take the time to fully understand the problem before making any fixes.
+      * **ALWAYS** read at least one new file for each compile error.
+      * **ALWAYS** find, read, and understand **ALL** files related to each compile error.
+      * **ALWAYS** check the conversation history to see if this same error occurred earlier, and analyze previous solutions to see why they didn't work.
+      * **NEVER** make speculative fixes. You should be confident before applying any fix that it will work. If you are not confident, read more files.
+6.  **Test:** **ALWAYS** run relevant tests after a successful build. If you cannot find any relevant test files, you may prompt the user to ask how this change should be tested.
+7.  **Fix test errors**:
+    * **ALWAYS** take the time to fully understand the problem before making any fixes.
+8.  **Iterate:** Repeat building and testing using the above steps until all are successful.

_agents/prompts/common.minimal.md

@@ -0,0 +1,44 @@
+# Gemini-CLI Specific Directives
+
+Instructions that apply only to gemini-cli.
+
+* When using the `read_file` tool:
+  * Always set the 'limit' parameter to 20000 to prevent truncation.
+* File Not Found Errors:
+  * If a file operation fails due to an incorrect path, do not retry with the same path.
+  * Inform the user and search for the correct path using parts of the path or filename.
+
+# Common Directives
+
+Instructions that are useful for Android Browser Helper development.
+
+## Paths
+
+* All files in the project's source can be read relative to the workspace root.
+
+## Building
+
+* Do not attempt a build without first establishing the correct target.
+* Build the project using Gradle:
+  * To build the entire project: `./gradlew build`
+  * To build a specific module (e.g., `androidbrowserhelper`): `./gradlew :androidbrowserhelper:assembleDebug`
+
+## Testing
+
+* Run tests using Gradle:
+  * To run all unit tests: `./gradlew test`
+  * To run unit tests for a specific module: `./gradlew :androidbrowserhelper:test`
+  * To run instrumentation tests (if emulator is available): `./gradlew connectedAndroidTest`
+
+## Coding
+
+* Stay on task: Do not address code health issues or TODOs in code unless it is required to achieve your given task.
+* Add code comments sparingly: Focus on *why* something is done, not *what* is done.
+
+## Git Operations
+
+* **Always branched:** Ensure you are not on the `main` branch if you are making commits. If you are, first do `git checkout -b {BRANCH_NAME}`.
+* **Commit messages:**
+  * Use active voice and avoid passive voice.
+  * Use present tense or imperative mood (e.g., "Change foo" instead of "Changed foo").
+  * Wrap the commit message at 72 characters when possible.

_agents/rules/CODE_STRUCTURE.md

@@ -0,0 +1,21 @@
+# Code Structure
+
+This document outlines the directory structure and modules of the Android Browser Helper project.
+
+## Modules
+
+The project is divided into the following modules:
+
+*   **[:androidbrowserhelper](../../androidbrowserhelper)**: The core library containing helper classes for Custom Tabs and Trusted Web Activities (TWA).
+    *   `src/main/java`: Source code for the core library.
+    *   `src/test/java`: Robolectric unit tests.
+    *   `src/androidTest/java`: Android instrumentation tests.
+*   **[:locationdelegation](../../locationdelegation)**: An optional library to delegate location permission requests from the TWA to the Android app.
+*   **[:playbilling](../../playbilling)**: An optional library to enable Google Play Billing inside TWAs.
+*   **[:demos](../../demos)**: A collection of demo applications demonstrating various features of the library.
+
+## Key Classes in `:androidbrowserhelper`
+
+*   **[`LauncherActivity`](../../androidbrowserhelper/src/main/java/com/google/androidbrowserhelper/trusted/LauncherActivity.java)**: Entry point activity for launching a TWA.
+*   **[`TwaLauncher`](../../androidbrowserhelper/src/main/java/com/google/androidbrowserhelper/trusted/TwaLauncher.java)**: Handles the complexity of connecting to the Custom Tabs service and launching the TWA.
+*   **[`TwaProviderPicker`](../../androidbrowserhelper/src/main/java/com/google/androidbrowserhelper/trusted/TwaProviderPicker.java)**: Chooses the best browser on the device to launch the TWA.

_agents/rules/DEPENDENCIES.md

@@ -0,0 +1,18 @@
+# Dependency Management
+
+This document outlines the policy for managing dependencies in the Android Browser Helper project.
+
+## Core Goal: Keep the Library Lightweight
+
+Android Browser Helper is a library that other Android applications depend on. To minimize the impact on the size of the consuming applications (the "app size"), we must keep our dependency footprint as small as possible.
+
+## Encouraged Dependencies
+
+*   **AndroidX libraries**: Prefer using official AndroidX libraries (e.g., `androidx.core`, `androidx.browser`) for compatibility and standard functionality.
+*   **Existing dependencies**: Reuse existing dependencies listed in `gradle/libs.versions.toml` (e.g., Guava, though we should use it sparingly if standard Java alternatives exist).
+
+## Banned / Discouraged Dependencies
+
+*   **No New External Libraries**: Do not add new external libraries (libraries not currently in `libs.versions.toml`) without a strong justification and approval from maintainers.
+*   **Kotlin (in core library)**: The core `:androidbrowserhelper` module is currently pure Java. Avoid adding Kotlin dependencies to the core library to prevent transitive dependency issues for pure Java apps using this library. (Kotlin is acceptable in demos or optional modules if justified, but currently not used).
+*   **Heavy Frameworks**: Avoid adding large frameworks that significantly increase the binary size.