docs: add contribution guidelines, issue templates, and refine docs

.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

.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

.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)
+
+<!-- If PR closes an issue, add its number so it links and auto-closes on merge, e.g. Fixes #123 -->
+Fixes #<issue-number>

.github/conventional-commit-lint.yaml

@@ -0,0 +1,2 @@
+enabled: true
+always_check_pr_title: true

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

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.