From 6838e09a89ab03b7f0d19c88258b6abc1e266e72 Mon Sep 17 00:00:00 2001 From: Sampath Kumar Date: Wed, 19 Aug 2026 17:48:23 +0000 Subject: [PATCH 1/2] doc: update documentation for clarity and conciseness Refine language across repository documentation, including README files and specification documents, to improve readability and flow. --- README.md | 14 +++++++------- internal/README.md | 10 +++++----- specification/COMPLIANCE.md | 2 +- specification/README.md | 4 ++-- specification/SPEC.md | 2 +- 5 files changed, 16 insertions(+), 16 deletions(-) diff --git a/README.md b/README.md index 9081b41..f2d8cf2 100644 --- a/README.md +++ b/README.md @@ -8,23 +8,23 @@ -The **A2A CLI** (`a2a`) provides a standardized command-line client interface for discovering, interacting with, and managing [A2A (Agent2Agent) agents](https://a2a-protocol.org/latest/). +The **A2A CLI** (`a2a`) is a standardized command-line client for discovering, interacting with, and managing [A2A (Agent2Agent) agents](https://a2a-protocol.org/latest/). > [!IMPORTANT] > **Specification in Active Review (v0.2)** -> This repository is currently focused on formalizing and reviewing the **A2A CLI Specification**. We welcome feedback, questions, and contributions on the specification documents as we prepare for v0.2 finalization in **August 2026**. +> We are formalizing and reviewing the **A2A CLI Specification**. Share feedback, questions, and contributions on the specification documents as we finalize v0.2 in **August 2026**. ## About the Project -While several community-driven CLI tools exist across different languages, they vary in coverage and behavior. To prevent ecosystem fragmentation, this project defines the **standardized, officially supported CLI specification and reference implementation** designed for long-term stability, cross-transport consistency, and community alignment. +Several community-driven CLI tools exist across languages, but they vary in coverage and behavior. To prevent fragmentation, this project defines one **standardized, officially supported CLI specification and reference implementation** — built for long-term stability, cross-transport consistency, and community alignment. -To bootstrap development, the initial codebase is based on the foundational CLI from the [A2A Go SDK](https://github.com/a2aproject/a2a-go/tree/9d95b95445f4208ba77f48a137a278067937adb7#-cli), which will be refined and expanded to conform with the finalized specification. +The initial codebase builds on the CLI from the [A2A Go SDK](https://github.com/a2aproject/a2a-go/tree/9d95b95445f4208ba77f48a137a278067937adb7#-cli). We will refine and expand it to match the finalized specification. ## Specification & Conformance (Core Focus) -The specification is a standalone document to defines the CLI behavior, command surface, output schemas, and transport rules for `a2a-cli`: +The specification is a standalone document that defines the CLI behavior, command surface, output schemas, and transport rules for `a2a-cli`: * **[Specification Document (v0.2)](./specification/SPEC.md):** The normative behavior specification covering command taxonomy, output contracts, polling/streaming rules, and exit codes. * **[Compliance Model (v0.2)](./specification/COMPLIANCE.md):** The requirement registry and verification model for claiming conformance. @@ -33,7 +33,7 @@ The specification is a standalone document to defines the CLI behavior, command ## CLI Development Phases & Roadmap -The specification organizes CLI capabilities into three cumulative tiers. Its development and implementation will roll out sequentially across these tiers: +The specification organizes CLI capabilities into three cumulative tiers. We will build and ship them in order: * **Tier 1 (Core Requirements):** Essential foundation — agent card discovery (`discover`), basic messaging (`send`), task inspection (`get task`), cancellation (`cancel`), polling, exit codes, and standard text/JSON output contracts. * **Tier 2 (Standard Features):** Expanded capabilities — task listing (`list tasks`), real-time event streaming (`subscribe`), transport auto-negotiation (REST, JSON-RPC, gRPC), push-configuration, and auth management. @@ -42,7 +42,7 @@ The specification organizes CLI capabilities into three cumulative tiers. Its de ## How to Contribute & Provide Feedback -We actively invite review and input from engineers and the broader community: +We invite review and input from engineers and the broader community: 1. Read the **[Specification Document (`SPEC.md`)](./specification/SPEC.md)**. 2. Review the **[Compliance Checklist (`COMPLIANCE.md`)](./specification/COMPLIANCE.md)**. diff --git a/internal/README.md b/internal/README.md index 2e69f17..407e65d 100644 --- a/internal/README.md +++ b/internal/README.md @@ -3,7 +3,7 @@ > [!WARNING] > This repository is in an alpha stage. -A command-line client for developers to send messages to A2A agents and services and receive task updates from them. +A command-line client for developers to send messages to A2A agents and services and receive task updates. ## Install @@ -191,7 +191,7 @@ a2a serve --proxy https://upstream-agent.com \ --svc-param "X-Trace-ID=debug-session-1" ``` -The proxy creates an `a2aclient.Client` for the upstream agent and forwards each A2A operation. Service parameters specified via `--svc-param` are injected into every forwarded request using `a2aclient.AttachServiceParams`. The proxy's own agent card is derived from the upstream card with the local interface address substituted. +The proxy creates an `a2aclient.Client` for the upstream agent and forwards each A2A operation. It injects any `--svc-param` service parameters into every forwarded request via `a2aclient.AttachServiceParams`, and derives its own agent card from the upstream card, substituting the local interface address. ### `--exec` - Exec Mode @@ -213,12 +213,12 @@ a2a serve --exec "./content-generator.sh" #### Output Modes -**Default (no `--chunk`):** The entire stdout is collected and emitted as a single text artifact when the process exits. +**Default (no `--chunk`):** The CLI collects all stdout and emits it as a single text artifact when the process exits. ``` Status: working → [process runs] → Artifact (full output) → Status: completed ``` -**With `--chunk=`:** stdout is read incrementally and split by the delimiter. Each piece is streamed as an artifact chunk event (`Append: true`) as soon as it's available. This enables streaming without requiring the subprocess to know about A2A's event model. +**With `--chunk=`:** The CLI reads stdout incrementally and splits it on the delimiter. It streams each piece as an artifact chunk event (`Append: true`) as soon as it's available, so the subprocess never needs to know A2A's event model. ```bash # Emit 3 chunks with 500ms delay - useful for verifying client streaming @@ -246,4 +246,4 @@ StatusUpdate: completed ## Output Formatting All commands support `-o json` for machine-readable output, emitting raw protocol objects. -Text mode is the default and is intended for reading in a terminal. +Text mode is the default, meant for reading in a terminal. diff --git a/specification/COMPLIANCE.md b/specification/COMPLIANCE.md index fccd0f9..fa44bab 100644 --- a/specification/COMPLIANCE.md +++ b/specification/COMPLIANCE.md @@ -37,7 +37,7 @@ An implementation declares what it supports **per tier**. The tiers themselves **Satisfying a tier.** A tier is satisfied only when **every applicable requirement listed for it** is satisfied. Claiming a tier holds the implementation to all of that tier's requirements, including any expressed as SHOULD in the specification's prose, which the claim promotes to required for that tier. A requirement that is inapplicable (the Agent Skill rows, when the tool ships no skill) does not count against the tier; one that applies but could not be exercised is **not** thereby satisfied. Tiers are cumulative: Tier 2 requires Tier 1, Tier 3 requires Tier 2. -**Evidence.** A tier claim MUST be demonstrated by a completed report: the tool exercised against a **live A2A agent**, with an outcome recorded for every requirement identifier in the tier claimed. An implementation MUST NOT advertise a tier it has not demonstrated. A reporter SHOULD state that the agent tested against is itself TCK-conformant, so a failure can be attributed to the CLI rather than to the agent. *Why: the A2A Technology Compatibility Kit validates agents, not clients, so it cannot grade an `a2a-cli`; reporting against a non-conformant agent measures two unknowns instead of one.* +**Evidence.** A tier claim MUST be demonstrated by a completed report: the tool exercised against a **live A2A agent**, with an outcome recorded for every requirement identifier in the tier claimed. An implementation MUST NOT advertise a tier it has not demonstrated. A reporter SHOULD state that the agent tested against is itself TCK-conformant, so you can attribute a failure to the CLI, not the agent. *Why: the A2A Technology Compatibility Kit validates agents, not clients, so it cannot grade an `a2a-cli`; reporting against a non-conformant agent measures two unknowns instead of one.* **Version pinning.** §1 records the specification version and — while that version is pre-Proposed (`SPEC.md` §15.1) — the revision date measured against. A pre-Proposed requirement can change between revisions, so a result that does not say which revision it measured cannot be interpreted later. diff --git a/specification/README.md b/specification/README.md index 001b39d..f181cfb 100644 --- a/specification/README.md +++ b/specification/README.md @@ -1,6 +1,6 @@ # a2a-cli Specification -This directory holds the specification for **`a2a-cli`** — the command-line client for the [Agent2Agent (A2A) Protocol](https://a2a-protocol.org/latest/specification/) — together with the material used to verify an implementation against it. +This directory holds the specification for **`a2a-cli`** — the command-line client for the [Agent2Agent (A2A) Protocol](https://a2a-protocol.org/latest/specification/) — together with the material for verifying an implementation against it. `a2a-cli` lets developers and AI coding agents fetch Agent Cards, send messages, stream and poll tasks, and read artifacts from the terminal. `SPEC.md` defines how the tool behaves, in terms an implementation in any language can follow. @@ -29,7 +29,7 @@ See [`SPEC.md`](./SPEC.md) for the normative detail. Tier membership is a scope decision and lives in `SPEC.md`. Everything about *claiming* a tier — what counts as satisfying a requirement, and the evidence a claim needs — lives in [`COMPLIANCE.md`](./COMPLIANCE.md). 1. Implement a tier of the specification. -2. Exercise the tool against a live A2A agent — ideally one that is itself TCK-conformant, so a failure can be attributed to the client rather than to the agent. The TCK validates *agents*, not clients, so it cannot grade a CLI directly. +2. Exercise the tool against a live A2A agent — ideally one that is itself TCK-conformant, so you can attribute a failure to the client, not the agent. The TCK validates *agents*, not clients, so it cannot grade a CLI directly. 3. Complete [`COMPLIANCE.md`](./COMPLIANCE.md), recording an outcome for every requirement identifier in the tier claimed. 4. Publish the machine-readable report alongside the implementation. diff --git a/specification/SPEC.md b/specification/SPEC.md index 59f8d37..9e50c6f 100644 --- a/specification/SPEC.md +++ b/specification/SPEC.md @@ -46,7 +46,7 @@ An `a2a-cli` is an **A2A client**: a unified command-line tool that lets human d 2.2 **Maximize developer convenience, learnability, and ergonomics.** Make discovering, learning, and driving the tool effortless from day one. The CLI provides opinionated, sensible defaults — such as blocking waits on task completion, automatic server-preference transport negotiation, and well-known card resolution — that minimize boilerplate flags while keeping every behavior overridable (§6.5) and discoverable via built-in `--help`. -2.3 **Built for the AI era: seamless for both human developers and AI coding agents.** With the rapid adoption of AI coding agents, autonomous agentic harnesses, and human-in-the-loop workflows, the CLI is designed from the ground up to serve humans and AI agents as first-class peers (§6.1). It provides a human-friendly, pipe-safe `text` format for interactive terminal use, protocol-native `json`/JSONL streaming for automated consumption (§11.3), and ships with a lean, standardized Agent Skill descriptor (`SKILL.md`, §14) so coding harnesses can delegate tasks to A2A instances with zero friction. +2.3 **Built for the AI era: seamless for both human developers and AI coding agents.** As AI coding agents, autonomous agentic harnesses, and human-in-the-loop workflows proliferate, the CLI serves humans and AI agents as first-class peers (§6.1). It provides a human-friendly, pipe-safe `text` format for interactive terminal use, protocol-native `json`/JSONL streaming for automated consumption (§11.3), and ships with a lean, standardized Agent Skill descriptor (`SKILL.md`, §14) so coding harnesses can delegate tasks to A2A instances with zero friction. 2.4 **Serve as a definitive implementation guide and capability roadmap.** Provide an authoritative, language-agnostic blueprint that guides engineers building or enhancing an `a2a-cli`. Through a structured, cumulative capability roadmap (Tier 1 Core, Tier 2 Standard, Tier 3 Advanced; §5) paired with a companion verification checklist (`COMPLIANCE.md`), it gives implementers a clear path for what to build first, next, and later, while making it straightforward to measure and demonstrate progress. From 3a3b48b7de961905acee6f1338ebc33ab91b4876 Mon Sep 17 00:00:00 2001 From: Sampath Kumar Date: Wed, 19 Aug 2026 23:15:05 +0000 Subject: [PATCH 2/2] docs: add project contribution and issue templates --- .github/ISSUE_TEMPLATE/bug-report.yml | 72 ++++++++++ .github/ISSUE_TEMPLATE/feature-request.yml | 80 +++++++++++ .../PULL_REQUEST_TEMPLATE.md | 23 +++ .github/conventional-commit-lint.yaml | 2 + CODE_OF_CONDUCT.md | 132 ++++++++++++++++++ CONTRIBUTING.md | 45 ++++++ README.md | 2 + SECURITY.md | 3 + specification/SPEC.md | 6 +- 9 files changed, 362 insertions(+), 3 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug-report.yml create mode 100644 .github/ISSUE_TEMPLATE/feature-request.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/conventional-commit-lint.yaml create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md diff --git a/.github/ISSUE_TEMPLATE/bug-report.yml b/.github/ISSUE_TEMPLATE/bug-report.yml new file mode 100644 index 0000000..a41173b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug-report.yml @@ -0,0 +1,72 @@ +name: 🐞 Bug Report +description: Report a bug in the A2A CLI +title: "bug: " +labels: ["bug"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to file a bug report! The more detail you can share, the faster we can reproduce and fix it. + + **Note:** Commits, issue titles, and pull request titles all follow the [Conventional Commits](https://www.conventionalcommits.org/) specification. + - type: checkboxes + id: area + attributes: + label: Which area does this relate to? + description: Select all that apply. + options: + - label: CLI code + - label: SPEC or COMPLIANCE file + - label: Other doc files + - type: textarea + id: what-happened + attributes: + label: What happened? + description: Describe the bug, and tell us what you expected to happen instead. + placeholder: When I run `a2a ...`, I see ... but I expected ... + validations: + required: true + - type: textarea + id: reproduce + attributes: + label: Steps to reproduce + description: If you can, list the exact steps — including the full command — to reproduce the bug. + placeholder: | + 1. Run `a2a ...` + 2. ... + 3. See the error + - type: input + id: cli-version + attributes: + label: CLI version + description: Run `a2a --version` and paste the output. + placeholder: e.g. a2a 0.2.1 + validations: + required: true + - type: input + id: os + attributes: + label: Operating system & environment + description: Your OS and version, plus architecture if you know it. + placeholder: e.g. macOS 14.5 (arm64), Ubuntu 24.04 (x86_64), Windows 11 + validations: + required: true + - type: textarea + id: logs + attributes: + label: Relevant log output or error messages + description: Paste any relevant logs, stack traces, or error output. Re-run with `--debug` for more detail if you can. This is formatted as code automatically — no backticks needed. + render: shell + - type: textarea + id: context + attributes: + label: Additional context + description: Anything else that helps us understand or recreate the bug — screenshots, the agent or endpoint involved, relevant config, etc. + - type: checkboxes + id: terms + attributes: + label: Code of Conduct + description: By submitting this issue, you agree to follow our [Code of Conduct](https://github.com/a2aproject/a2a-cli/blob/main/CODE_OF_CONDUCT.md) + options: + - label: I agree to follow this project's Code of Conduct + required: true diff --git a/.github/ISSUE_TEMPLATE/feature-request.yml b/.github/ISSUE_TEMPLATE/feature-request.yml new file mode 100644 index 0000000..29ab3f0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature-request.yml @@ -0,0 +1,80 @@ +name: 💡 Feature Request +description: Suggest an idea for the A2A CLI +title: "feat: " +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + Thanks for helping improve the A2A CLI! Tell us what you'd like to see and why it matters. + + **Note:** Commits, issue titles, and pull request titles all follow the [Conventional Commits](https://www.conventionalcommits.org/) specification. + - type: checkboxes + id: area + attributes: + label: Which area does this relate to? + description: Select all that apply. + options: + - label: CLI code + - label: SPEC or COMPLIANCE file + - label: Other doc files + - type: dropdown + id: feature-type + attributes: + label: What kind of feature are you proposing? + options: + - New command or flag + - Change to an existing command or behavior + - Specification change (SPEC.md / COMPLIANCE.md) + - Documentation + - Developer experience / ergonomics + - Other + validations: + required: true + - type: textarea + id: describe + attributes: + label: What would you like to see? + description: A clear and concise description of the feature you're proposing. + validations: + required: true + - type: textarea + id: why + attributes: + label: Why is this important? + description: What problem does it solve, or what does it make possible that isn't today? + validations: + required: true + - type: textarea + id: who-benefits + attributes: + label: Who benefits from this feature? + description: What kind of developers or users does this help, and in what situation? + placeholder: e.g. CI/CD authors scripting agent calls, AI coding agents driving the CLI, ... + validations: + required: true + - type: dropdown + id: contribution + attributes: + label: Would you be interested in helping build this feature? + description: No pressure — proposing the idea is valuable on its own. + options: + - Yes — I'd like to implement it + - Yes — with some guidance + - I can help test or review + - "No — just proposing the idea" + validations: + required: true + - type: textarea + id: context + attributes: + label: Additional context + description: Anything else that helps — examples, links, screenshots, or alternatives you've considered. + - type: checkboxes + id: terms + attributes: + label: Code of Conduct + description: By submitting this issue, you agree to follow our [Code of Conduct](https://github.com/a2aproject/a2a-cli/blob/main/CODE_OF_CONDUCT.md) + options: + - label: I agree to follow this project's Code of Conduct + required: true diff --git a/.github/PULL_REQUEST_TEMPLATE/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..bbac136 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,23 @@ +# Description + +Thank you for opening a Pull Request! + +**Note:** Commits, issue titles, and pull request titles all follow the [Conventional Commits](https://www.conventionalcommits.org/) specification. + +## Which area does this relate to? + +- [ ] CLI code +- [ ] SPEC or COMPLIANCE file +- [ ] Other doc files + +## Checklist + +Before submitting, run through this checklist so your PR goes smoothly: + +- [ ] Review the [Contributing guide](https://github.com/a2aproject/a2a-cli/blob/main/CONTRIBUTING.md). +- [ ] Make your Pull Request title follow the [Conventional Commits](https://www.conventionalcommits.org/) specification (e.g., `docs(spec):` for `specification/SPEC.md` changes, `docs:` for other docs, `feat:` / `fix:` for CLI code). PR titles are lint-checked. +- [ ] Ensure the code is formatted and the linter passes (`gofmt -w .` and `golangci-lint run`). +- [ ] Appropriate docs were updated (if necessary) + + +Fixes # diff --git a/.github/conventional-commit-lint.yaml b/.github/conventional-commit-lint.yaml new file mode 100644 index 0000000..c967ffa --- /dev/null +++ b/.github/conventional-commit-lint.yaml @@ -0,0 +1,2 @@ +enabled: true +always_check_pr_title: true diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..5e58482 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,132 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, caste, color, religion, or sexual +identity and orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the overall + community + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or advances of + any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email address, + without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. + +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official email address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders responsible for enforcement by reaching out to +a maintainer on our [Discord server](https://discord.com/invite/9UpukKSpRN). All +complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. + +## Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: + +### 1. Correction + +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. + +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. + +### 2. Warning + +**Community Impact**: A violation through a single incident or series of +actions. + +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or permanent +ban. + +### 3. Temporary Ban + +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. + +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. + +### 4. Permanent Ban + +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. + +**Consequence**: A permanent ban from any sort of public interaction within the +community. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. + +Community Impact Guidelines were inspired by [Mozilla's code of conduct +enforcement ladder][Mozilla CoC]. + +For answers to common questions about this code of conduct, see the FAQ at +[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at +[https://www.contributor-covenant.org/translations][translations]. + +[homepage]: https://www.contributor-covenant.org +[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html +[Mozilla CoC]: https://github.com/mozilla/diversity +[FAQ]: https://www.contributor-covenant.org/faq +[translations]: https://www.contributor-covenant.org/translations diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..30d5f8d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,45 @@ +# How to contribute + +We'd love to accept your patches and contributions to this project. This repository holds two things: the **A2A CLI specification** (`specification/SPEC.md`, `specification/COMPLIANCE.md`) and its **Go reference implementation** (`a2a`). Contributions to either are welcome. + +## Ways to contribute + +Code is only one way to help. The project grows through many kinds of contribution: + +- **Request a feature.** Open a [feature request](https://github.com/a2aproject/a2a-cli/issues/new?template=feature-request.yml) to propose a new command, flag, or specification change. +- **Report a bug.** File a [bug report](https://github.com/a2aproject/a2a-cli/issues/new?template=bug-report.yml) with steps to reproduce, your CLI version, and your OS. +- **Contribute code.** Fix a bug or build a feature — see the workflow below. +- **Improve the docs.** Clarify the README, the specification, or these guidelines. +- **Share feedback.** Tell us how you use the tool, what works, and what's rough — on our [Discord server](https://discord.com/invite/9UpukKSpRN) or in an issue. +- **Help the community.** Answer questions, help reproduce and triage issues, and review pull requests. + +## Before you start + +- Read our [Code of Conduct](./CODE_OF_CONDUCT.md). By participating, you agree to follow it. +- For a quick chat or to say Hi, reach out on our [Discord server](https://discord.com/invite/9UpukKSpRN). +- For anything actionable, open an [issue](https://github.com/a2aproject/a2a-cli/issues) or [pull request](https://github.com/a2aproject/a2a-cli/pulls). + +## Conventional Commits + +Commit messages and pull request titles follow the [Conventional Commits](https://www.conventionalcommits.org/) specification. PR titles are lint-checked. Choose the type and scope based on what you changed: + +- **CLI code** — `feat:` for new behavior, `fix:` for bug fixes (e.g., `feat: add subscribe command`). +- **SPEC or COMPLIANCE file** — `docs(spec):` for changes to `specification/SPEC.md` or `specification/COMPLIANCE.md`. +- **Other doc files** — `docs:` for all other documentation. + +## Contribution process + +### Code reviews + +We use GitHub pull requests for reviews. See [GitHub Help](https://help.github.com/articles/about-pull-requests/) for how to use them. + +### Workflow + +1. **Fork** the official repository to your own account. +2. **Sync** your fork with the latest changes from `main`. +3. **Create a feature branch** and make your changes there. +4. **Commit** using a Conventional Commits message. +5. **Open a pull request** from your feature branch to the official repository's `main` branch. +6. **Resolve feedback** — work with reviewers to address comments. + +Be patient — reviewing and merging a pull request can take time. diff --git a/README.md b/README.md index f2d8cf2..8aac2f4 100644 --- a/README.md +++ b/README.md @@ -48,6 +48,8 @@ We invite review and input from engineers and the broader community: 2. Review the **[Compliance Checklist (`COMPLIANCE.md`)](./specification/COMPLIANCE.md)**. 3. Open an issue or pull request in this repository to share suggestions, questions, or edge cases. +You can also help us in other ways like sharing how you use the tool. See the **[Contributing guide](CONTRIBUTING.md)** to get started. + ## License diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..6aaac1e --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,3 @@ +# Security Policy + +To report a security issue, privately contact our moderators or an A2A TSC member on our [Discord server](https://discord.com/invite/9UpukKSpRN) for faster review. Do not open a public issue. diff --git a/specification/SPEC.md b/specification/SPEC.md index 9e50c6f..c904b67 100644 --- a/specification/SPEC.md +++ b/specification/SPEC.md @@ -28,9 +28,9 @@ References of the form "A2A §x" point to the A2A Protocol Specification v1.0. W A2A has a stable protocol and a growing set of agents. What it does not yet have is one agreed way to talk to them from a command line. -**Eleven CLIs already exist, and they rebuild the same five commands.** Across six languages, every one of them sends a message and fetches an Agent Card, ten stream, nine read task status, nine cancel — and only four list tasks, only three configure push notifications ([A2A#1929](https://github.com/a2aproject/A2A/issues/1929#issuecomment-5326727779)). The common path has been settled by practice; the harder half of the protocol is unbuilt in nearly all of them. This document writes down what implementers already converged on rather than inventing a design, and names the surface that fragmentation has left unfinished. +**Eleven CLIs already exist, and they rebuild the same five commands.** Across six languages, every one of them sends a message and fetches an Agent Card, ten stream, nine read task status, nine cancel — and only four list tasks, only three configure push notifications ([A2A#1929](https://github.com/a2aproject/A2A/issues/1929#issuecomment-5326727779)). Practice has settled the common path; the harder half of the protocol is unbuilt in nearly all of them. This document writes down what implementers already converged on rather than inventing a design, and names the surface that fragmentation has left unfinished. -**A2A's developer-tooling layer is still forming, and a command line is the shortest way in.** The protocol reached a stable [v1.0](https://github.com/a2aproject/A2A/releases) in March 2026, and support has kept growing — from more than 100 organisations at the Linux Foundation launch to [169 listed today](https://a2a-protocol.org/latest/partners/), with the Python SDK alone pulling over 16 million downloads a month. That growth has landed mainly in agent frameworks and enterprise platforms: among coding harnesses, adoption is comparatively close to nonexistent — one or two document A2A support today, and where it exists it is described as experimental. A single specified CLI, shipped with one skill descriptor, offers both audiences the same low-friction entry point: a developer can exercise a deployed agent in one command, and a coding agent can drive that same command from its [skill file](https://agentskills.io/skill-creation/using-scripts.md). +**A2A's developer-tooling layer is still forming, and a command line is the shortest way in.** The protocol reached a stable [v1.0](https://github.com/a2aproject/A2A/releases) in March 2026, and support has kept growing — from more than 100 organisations at the Linux Foundation launch to [169 listed today](https://a2a-protocol.org/latest/partners/), with the Python SDK alone pulling over 16 million downloads a month. That growth has landed mainly in agent frameworks and enterprise platforms: among coding harnesses, adoption is nearly nonexistent — one or two document A2A support today, and where it exists, it is labeled experimental. A single specified CLI, shipped with one skill descriptor, offers both audiences the same low-friction entry point: a developer can exercise a deployed agent in one command, and a coding agent can drive that same command from its [skill file](https://agentskills.io/skill-creation/using-scripts.md). @@ -42,7 +42,7 @@ This specification writes that common path down once — the core client behavio An `a2a-cli` is an **A2A client**: a unified command-line tool that lets human developers, automated workflows, and AI coding harnesses send tasks, stream updates, and fetch artifacts from any A2A-supported agent instance. This specification sets out four core goals to resolve the fragmentation, tooling gaps, and lack of standard guidance described in §1. They state the outcomes this specification achieves, not the operative rules (which are defined in §6–§14): -2.1 **Deliver complete protocol coverage and multi-transport support.** Go beyond the fragmented basic commands (`card get`, `send`) that existing ad-hoc tools re-invented to specify the full breadth of the A2A Protocol. An `a2a-cli` covers all A2A transport bindings (JSON-RPC, HTTP+JSON, and gRPC), lifecycle event streaming and polling, push notifications, and enterprise security across cumulative capability tiers (§5), ensuring a unified, predictable command surface across languages. +2.1 **Deliver complete protocol coverage and multi-transport support.** Go beyond the fragmented basic commands (`card get`, `send`) that ad-hoc tools re-invented, and specify the full breadth of the A2A Protocol. An `a2a-cli` covers all A2A transport bindings (JSON-RPC, HTTP+JSON, and gRPC), lifecycle event streaming and polling, push notifications, and enterprise security across cumulative capability tiers (§5), for a unified, predictable command surface across languages. 2.2 **Maximize developer convenience, learnability, and ergonomics.** Make discovering, learning, and driving the tool effortless from day one. The CLI provides opinionated, sensible defaults — such as blocking waits on task completion, automatic server-preference transport negotiation, and well-known card resolution — that minimize boilerplate flags while keeping every behavior overridable (§6.5) and discoverable via built-in `--help`.