feat: contributors folder, CI review gates, and contributor program issues

.github/BRANCH_PROTECTION.md

@@ -0,0 +1,42 @@
+# Branch Protection Setup (Maintainers)
+
+Community PRs must **not merge without review**. Configure these settings on the `main` branch in GitHub:
+
+**Settings → Branches → Branch protection rules → `main`**
+
+## Required settings
+
+1. **Require a pull request before merging**
+   - Require approvals: **1** (or more)
+   - Dismiss stale pull request approvals when new commits are pushed: recommended
+
+2. **Require review from Code Owners** (optional but recommended)
+   - Uses [.github/CODEOWNERS](./CODEOWNERS) (`@fetchai`)
+
+3. **Require status checks to pass before merging**
+   - Require branches to be up to date before merging: recommended
+   - Required checks (match workflow job names in `pull_request_ci.yml`):
+     - `stargazer-gate`
+     - `contributor-path-check`
+     - `changelog-check`
+     - `review-required`
+     - `lint`
+     - `format`
+     - `typecheck`
+     - `validate-architecture`
+     - `test`
+
+4. **Do not allow bypassing the above settings** (recommended for `main`)
+
+5. **Restrict who can push to matching branches** (optional)
+   - Prevents direct pushes to `main`
+
+## CI vs GitHub settings
+
+- The `review-required` workflow job fails until a reviewer approves the PR.
+- Branch protection must list `review-required` as a required check, or merges can still proceed if only other checks are required.
+- Admins can bypass protection unless "Include administrators" is enforced.
+
+## After updating workflows
+
+When new jobs are added to `pull_request_ci.yml`, re-open branch protection and add the new check names to the required list.

.github/ISSUE_TEMPLATE/config.yml

@@ -1,5 +1,8 @@
 blank_issues_enabled: false
 contact_links:
+  - name: Community Contributors Guide
+    url: https://github.com/fetchai/innovation-lab-examples/blob/main/contributors/README.md
+    about: How to add your agent under contributors/ and open a PR.
   - name: Contribution and Issue Guide
     url: https://github.com/fetchai/innovation-lab-examples/blob/main/ISSUES_GUIDE.md
     about: Read the issue and contribution requirements before creating a new issue.

.github/ISSUE_TEMPLATE/contributor_good_first.yml

@@ -0,0 +1,42 @@
+name: Contributor — good first issue
+description: Pick up a starter task to improve docs, examples, or contributor experience.
+title: "[Contributor] "
+labels: ["good first issue", "help wanted"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for contributing! Read [contributors/README.md](../../contributors/README.md) and [CONTRIBUTING.md](../../CONTRIBUTING.md) before you start.
+
+  - type: textarea
+    id: task
+    attributes:
+      label: Task description
+      description: What will you implement or fix?
+      value: |
+        Example tasks:
+        - Add missing `.env.example` to an example under `contributors/` or document env vars in README
+        - Fix broken setup steps in a contributor agent README
+        - Add demo screenshot under `contributors/<agent>/assets/`
+    validations:
+      required: true
+
+  - type: input
+    id: folder
+    attributes:
+      label: Target folder (if applicable)
+      placeholder: contributors/my-agent-name
+    validations:
+      required: false
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Contributor checklist
+      options:
+        - label: I will place new agents under `contributors/<agent-name>/` only
+          required: true
+        - label: I will update `contributors/CHANGELOG.md` for non-doc changes
+          required: true
+        - label: I have starred this repository
+          required: true

.github/ISSUE_TEMPLATE/realtime_agent_challenge.yml

@@ -0,0 +1,61 @@
+name: Challenge — real-time AI agent
+description: Propose or claim work on a real-time transactional agent (booking, payments, live APIs).
+title: "[Challenge] Real-time agent: "
+labels: ["enhancement", "help wanted", "challenge"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Build a **production-style demo agent** that handles a real-time or transactional workflow.  
+        Submit your implementation under **`contributors/<your-agent-name>/`**.
+
+        Reference patterns in the repo:
+        - Flights: `duffel-agent/`, `flight-tracker-openai-workflow-agent/`
+        - Payments: `stripe-payment-agents/`, `stripe-horoscope-agent/`
+        - Live discovery: `mcp-agents/ticketlens-agent/`
+
+  - type: dropdown
+    id: domain
+    attributes:
+      label: Agent domain
+      options:
+        - Flight booking / search
+        - Hotel booking / search
+        - Payment gateway / Stripe gating
+        - Event tickets / live inventory
+        - Multi-step trip planner (flights + hotels)
+        - Other (describe below)
+    validations:
+      required: true
+
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Your approach
+      description: APIs (sandbox preferred), agent flow, and Fetch.ai stack (uAgents, ASI:One, Agentverse, MCP, A2A).
+    validations:
+      required: true
+
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance criteria
+      description: What should work in the demo?
+      value: |
+        - [ ] Runnable locally with `.env.example` and README
+        - [ ] Clear user-facing chat or CLI flow
+        - [ ] Uses sandbox/mock mode where real charges apply
+        - [ ] Demo screenshot in `assets/`
+        - [ ] Entry added to `contributors/CHANGELOG.md` and root README community table
+    validations:
+      required: true
+
+  - type: checkboxes
+    id: checklist
+    attributes:
+      label: Before opening a PR
+      options:
+        - label: Agent will live under `contributors/<name>/` only
+          required: true
+        - label: No real API keys or secrets in the PR
+          required: true

.github/MAINTAINERS

@@ -0,0 +1,5 @@
+# GitHub usernames with maintainer privileges (skip review-required & stargazer-gate).
+# Automatically skipped: @fetchai org members and users with write/admin on this repo.
+# Add your GitHub username below (one per line). Lines starting with # are ignored.
+
+gautammanak1

.github/pull_request_template.md

@@ -13,14 +13,17 @@ Describe what this PR changes.
 ## Checklist
 
 - [ ] I have starred this repository.
+- [ ] **New community agents** are under `contributors/<agent-name>/` (not repo root).
 - [ ] I ran `ruff check .`.
 - [ ] I ran `ruff format .`.
 - [ ] I added/updated `README.md` for changed example(s).
 - [ ] I added `.env.example` if environment variables are required.
 - [ ] I added demo image/GIF (if applicable).
 - [ ] I added agent profile link (if applicable).
-- [ ] I updated `CHANGELOG.md` (required for non-doc changes).
+- [ ] I updated `contributors/CHANGELOG.md` for community agent changes, or root `CHANGELOG.md` for other non-doc changes.
+- [ ] I added my agent to the **Community Contributors** table in root `README.md` (if new agent).
 - [ ] I verified paths/commands used in docs.
+- [ ] I understand this PR **requires maintainer review** before merge (`review-required` CI).
 
 ## Related Issue