docs: add OSS Contributor Accelerator template example

examples/templates/README.md

@@ -44,3 +44,4 @@ uv run python -m exports.my_research_agent --input '{"topic": "..."}'
 |----------|-------------|
 | [deep_research_agent](deep_research_agent/) | Interactive research agent that searches diverse sources, evaluates findings with user checkpoints, and produces a cited HTML report |
 | [tech_news_reporter](tech_news_reporter/) | Researches the latest technology and AI news from the web and produces a well-organized report |
+| [oss_contributor_accelerator](oss_contributor_accelerator/) | Discovers high-leverage GitHub issues for a contributor and generates an execution-ready contribution brief with PR drafts |

examples/templates/oss_contributor_accelerator/DEMO.md

@@ -0,0 +1,41 @@
+# Demo Script (10-15 minutes)
+
+Use this to show the template's value quickly.
+
+## 1) Setup
+
+```bash
+./quickstart.sh
+```
+
+## 2) Copy template to exports
+
+```bash
+cp -r examples/templates/oss_contributor_accelerator exports/oss_contributor_accelerator
+```
+
+## 3) Run in TUI
+
+```bash
+hive run exports/oss_contributor_accelerator --tui
+```
+
+## 4) Suggested demo input
+
+- Repo: `aden-hive/hive`
+- Skills: `Python, agent frameworks, test automation, docs`
+- Time: `6 hours/week`
+- Preference: `quick win with meaningful impact`
+
+## 5) Success signal
+
+Agent should produce:
+- ranked shortlist of 8 issues
+- user-selected 1-3 issues
+- `contribution_brief.md` with implementation + tests + PR draft text
+
+## 6) What to share with reviewers
+
+- Brief screenshot/video of issue ranking
+- Final contribution_brief.md artifact
+- One concrete issue picked and implemented from the brief

examples/templates/oss_contributor_accelerator/README.md

@@ -0,0 +1,65 @@
+# OSS Contributor Accelerator
+
+**Version**: 1.0.0  
+**Type**: Multi-node agent template
+
+## Overview
+
+Find high-leverage issues in an OSS repo and generate an execution-ready contribution brief.
+
+This template is designed for contributors who want to ship meaningful PRs quickly:
+
+1. Collect contributor context (skills, time, preferences)
+2. Discover and rank issues from GitHub
+3. Let the user pick 1-3 targets
+4. Generate a markdown brief with implementation plan, test strategy, and PR drafts
+
+## Architecture
+
+Execution flow:
+
+```text
+intake -> issue-scout -> selection -> contribution-pack
+```
+
+### Nodes
+
+1. **intake** (client-facing)
+   - Collects repo + contributor context
+   - Output: `repo_context`
+
+2. **issue-scout**
+   - Uses GitHub APIs to shortlist/rank 8 issues
+   - Output: `shortlisted_issues`
+   - Tools: `github_get_repo`, `github_list_issues`, `github_get_issue`
+
+3. **selection** (client-facing)
+   - Presents ranked issues and captures user selection
+   - Output: `selected_issues`
+
+4. **contribution-pack** (client-facing, terminal)
+   - Generates `contribution_brief.md`
+   - Includes implementation plan, tests, PR title/body drafts, maintainer update draft
+   - Tools: `save_data`, `append_data`, `serve_file_to_user`
+
+## Goal Criteria
+
+- High-impact issue shortlist
+- Strong contributor-to-issue fit
+- Actionable implementation and test plans
+- PR-ready draft quality
+
+## Usage
+
+```bash
+# Copy template to exports
+cp -r examples/templates/oss_contributor_accelerator exports/my_oss_agent
+
+# Run
+uv run python -m exports.my_oss_agent run
+```
+
+## Notes
+
+- Requires GitHub credentials for GitHub tools.
+- Designed with human-in-the-loop selection before deep planning.

examples/templates/oss_contributor_accelerator/__init__.py

@@ -0,0 +1,5 @@
+"""OSS Contributor Accelerator template."""
+
+from .agent import OSSContributorAcceleratorAgent, default_agent
+
+__all__ = ["OSSContributorAcceleratorAgent", "default_agent"]

examples/templates/oss_contributor_accelerator/__main__.py

@@ -0,0 +1,90 @@
+"""CLI entry point for OSS Contributor Accelerator."""
+
+import asyncio
+import json
+import logging
+import sys
+
+import click
+
+from .agent import default_agent
+
+
+def setup_logging(verbose=False, debug=False):
+    """Configure logging."""
+    if debug:
+        level, fmt = logging.DEBUG, "%(asctime)s %(name)s: %(message)s"
+    elif verbose:
+        level, fmt = logging.INFO, "%(message)s"
+    else:
+        level, fmt = logging.WARNING, "%(levelname)s: %(message)s"
+    logging.basicConfig(level=level, format=fmt, stream=sys.stderr)
+    logging.getLogger("framework").setLevel(level)
+
+
+@click.group()
+@click.version_option(version="1.0.0")
+def cli():
+    """OSS Contributor Accelerator - turn issue backlog into shippable plans."""
+
+
+@cli.command()
+@click.option("--mock", is_flag=True, help="Run in mock mode")
+@click.option("--quiet", "-q", is_flag=True, help="Only output result JSON")
+@click.option("--verbose", "-v", is_flag=True, help="Show execution details")
+@click.option("--debug", is_flag=True, help="Show debug logging")
+def run(mock, quiet, verbose, debug):
+    """Execute the workflow."""
+    if not quiet:
+        setup_logging(verbose=verbose, debug=debug)
+
+    context = {}
+    result = asyncio.run(default_agent.run(context, mock_mode=mock))
+
+    output_data = {
+        "success": result.success,
+        "steps_executed": result.steps_executed,
+        "output": result.output,
+    }
+    if result.error:
+        output_data["error"] = result.error
+
+    click.echo(json.dumps(output_data, indent=2, default=str))
+    sys.exit(0 if result.success else 1)
+
+
+@cli.command()
+@click.option("--json", "output_json", is_flag=True)
+def info(output_json):
+    """Show agent information."""
+    info_data = default_agent.info()
+    if output_json:
+        click.echo(json.dumps(info_data, indent=2))
+    else:
+        click.echo(f"Agent: {info_data['name']}")
+        click.echo(f"Version: {info_data['version']}")
+        click.echo(f"Description: {info_data['description']}")
+        click.echo(f"\nNodes: {', '.join(info_data['nodes'])}")
+        click.echo(f"Client-facing: {', '.join(info_data['client_facing_nodes'])}")
+        click.echo(f"Entry: {info_data['entry_node']}")
+        click.echo(f"Terminal: {', '.join(info_data['terminal_nodes'])}")
+
+
+@cli.command()
+def validate():
+    """Validate agent structure."""
+    validation = default_agent.validate()
+    if validation["valid"]:
+        click.echo("Agent is valid")
+        if validation["warnings"]:
+            for warning in validation["warnings"]:
+                click.echo(f"  WARNING: {warning}")
+    else:
+        click.echo("Agent has errors:")
+        for error in validation["errors"]:
+            click.echo(f"  ERROR: {error}")
+    sys.exit(0 if validation["valid"] else 1)
+
+
+if __name__ == "__main__":
+    cli()

examples/templates/oss_contributor_accelerator/agent.json

@@ -0,0 +1,117 @@
+{
+  "agent": {
+    "id": "oss_contributor_accelerator",
+    "name": "OSS Contributor Accelerator",
+    "version": "1.0.0",
+    "description": "Rank high-leverage OSS issues and generate execution-ready contribution briefs with PR drafts."
+  },
+  "graph": {
+    "id": "oss-contributor-accelerator-graph",
+    "goal_id": "oss-contributor-accelerator",
+    "version": "1.0.0",
+    "entry_node": "intake",
+    "entry_points": {
+      "start": "intake"
+    },
+    "pause_nodes": [],
+    "terminal_nodes": [
+      "contribution-pack"
+    ],
+    "nodes": [
+      {
+        "id": "intake",
+        "name": "Intake",
+        "node_type": "event_loop",
+        "client_facing": true,
+        "input_keys": [],
+        "output_keys": [
+          "repo_context"
+        ]
+      },
+      {
+        "id": "issue-scout",
+        "name": "Issue Scout",
+        "node_type": "event_loop",
+        "client_facing": false,
+        "input_keys": [
+          "repo_context"
+        ],
+        "output_keys": [
+          "shortlisted_issues"
+        ],
+        "tools": [
+          "github_get_repo",
+          "github_list_issues",
+          "github_get_issue"
+        ]
+      },
+      {
+        "id": "selection",
+        "name": "Selection",
+        "node_type": "event_loop",
+        "client_facing": true,
+        "input_keys": [
+          "shortlisted_issues",
+          "repo_context"
+        ],
+        "output_keys": [
+          "selected_issues"
+        ]
+      },
+      {
+        "id": "contribution-pack",
+        "name": "Contribution Pack",
+        "node_type": "event_loop",
+        "client_facing": true,
+        "input_keys": [
+          "selected_issues",
+          "repo_context"
+        ],
+        "output_keys": [
+          "contribution_brief"
+        ],
+        "tools": [
+          "save_data",
+          "append_data",
+          "serve_file_to_user"
+        ]
+      }
+    ],
+    "edges": [
+      {
+        "id": "intake-to-issue-scout",
+        "source": "intake",
+        "target": "issue-scout",
+        "condition": "on_success",
+        "priority": 1
+      },
+      {
+        "id": "issue-scout-to-selection",
+        "source": "issue-scout",
+        "target": "selection",
+        "condition": "on_success",
+        "priority": 1
+      },
+      {
+        "id": "selection-to-contribution-pack",
+        "source": "selection",
+        "target": "contribution-pack",
+        "condition": "on_success",
+        "priority": 1
+      }
+    ]
+  },
+  "required_tools": [
+    "github_get_repo",
+    "github_list_issues",
+    "github_get_issue",
+    "save_data",
+    "append_data",
+    "serve_file_to_user"
+  ],
+  "metadata": {
+    "created_by": "template",
+    "node_count": 4,
+    "edge_count": 3
+  }
+}