README.md

---
title: SIN-GitHub-Issues
emoji: "🤖"
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false
---

# SIN-GitHub-Issues

`SIN-GitHub-Issues` is a SIN A2A agent package for the Silicon Workforce.

## Identity

- Slug: `sin-github-issues`
- Team: `Team - Coding`
- Team Manager: `SIN-Coding-CEO`
- Purpose: GitHub issue execution agent for confirmed bugs, repo issue lifecycle, branch-based fixes, and verification handoff. Extended with enterprise profile management capabilities.
- Usage: Use after enterprise-deep-debug confirms a bug to search/create/update GitHub issues, open a repo branch, execute the fix workflow, commit, push, and report verification status back to the orchestrating CLI agent. For profile and achievement operations use the new profile/achievement actions.
- Primary Model: `openai/gpt-5.4`

## Deployment

- Local path: `/Users/jeremy/dev/OpenSIN-backend/a2a/team-coding/A2A-SIN-GitHub-Issues`
- GitHub repo: `https://github.com/Delqhi/sin-github-issues`
- Workforce index: `https://a2a.delqhi.com`
- Landing page: `https://delqhi-sin-github-issues.hf.space`
- Public A2A / CIMD: `https://a2a.delqhi.com/agents/sin-github-issues`
- Hugging Face Space: `https://huggingface.co/spaces/delqhi/sin-github-issues`
- Hugging Face repo id: `delqhi/sin-github-issues`
- Cloudflare tunnel: `sin-github-issues`
- Runtime target: `Target: Hugging Face Space free CPU VM`

## Runtime Shape

- A2A JSON-RPC runtime
- MCP stdio runtime
- CLI wrapper for local and automated use
- publish-ready Docker/Hugging Face Space layout
- keep-alive ping + HF dataset session backup hooks
- best-effort `sin-supabase` audit persistence for workflow events
- canonical env names: `SUPABASE_URL` + `SUPABASE_SERVICE_ROLE_KEY` (legacy `SIN_SUPABASE_*` still accepted)

## GitHub App Fleet Routing

- Each specialized SIN coder can own its own dedicated GitHub App identity, for example `SIN-Hermes[bot]`, `SIN-Zeus[bot]`, or `SIN-BugBounty[bot]`.
- Central webhook endpoint: `POST /api/webhooks/github-apps`
- The current implementation prefers one central endpoint with `installation.app_id` routing.
- Routing key: `installation.app_id`
- Reply auth key: `installation.id`
- Routing config sources:
  - repo SSOT: `config/github-app-routing.json`
  - start-small example: `config/github-app-routing.local.example.json`
  - GitHub-Issues local example: `config/github-app-routing.example.json`
  - env matrix: `.env.example` and `.env.example` in this agent root
- Secret material is never committed. Use env-backed private key + webhook secret fields referenced from the routing config.

### Operator Setup

1. Generate a local routing file from the example template:

```bash
npm run ops:github-app-routing:init
npm run ops:github-app-routing:env-template -- --agents sin-hermes,sin-zeus,sin-bugbounty
npm run ops:github-app-routing:vm-rollout -- --agents sin-hermes,sin-zeus,sin-bugbounty --base-url https://your-vm-host
```

2. Export `SIN_GITHUB_APP_ROUTING_PATH=./config/github-app-routing.local.json`.
3. Fill the referenced env vars for each GitHub App in your runtime environment:
   - `SIN_HERMES_GITHUB_APP_ID`, `SIN_HERMES_GITHUB_APP_CLIENT_ID`, `SIN_HERMES_GITHUB_APP_PRIVATE_KEY_PEM`, `SIN_HERMES_GITHUB_APP_WEBHOOK_SECRET`
   - `SIN_ZEUS_GITHUB_APP_ID`, `SIN_ZEUS_GITHUB_APP_CLIENT_ID`, `SIN_ZEUS_GITHUB_APP_PRIVATE_KEY_PEM`, `SIN_ZEUS_GITHUB_APP_WEBHOOK_SECRET`
   - `SIN_GITHUB_ISSUES_GITHUB_APP_ID`, `SIN_GITHUB_ISSUES_GITHUB_APP_CLIENT_ID`, `SIN_GITHUB_ISSUES_GITHUB_APP_PRIVATE_KEY_PEM`, `SIN_GITHUB_ISSUES_GITHUB_APP_WEBHOOK_SECRET`
4. Point the selected GitHub Apps to the shared webhook path `POST /api/webhooks/github-apps`.
5. Validate the webhook router before going live:

```bash
npm run ops:github-app-routing:check -- --apps sin-hermes,sin-zeus,sin-github-issues
npm run ops:github-app-routing:smoke -- --app sin-hermes --base-url http://127.0.0.1:8000
npm run ops:github-app-routing:smoke -- --app sin-zeus --base-url http://127.0.0.1:8000
npm run ops:github-app-routing:smoke -- --app sin-github-issues --base-url http://127.0.0.1:8000
pytest tests/unit/test_room13_webhook_routes.py -q
```

The smoke command generates a signed synthetic GitHub webhook for the selected app and expects the Room-13 endpoint to resolve the configured `app_slug`, `preferred_agent_slug`, and `installation_id`.

## A2A Surface

- Card: `GET /.well-known/agent-card.json`
- Alias: `GET /.well-known/agent.json`
- Health: `GET /health`
- RPC: `POST /a2a/v1`

## MCP Surface

- Transport: `stdio`
- Config: `./mcp-config.json`
- OpenCode client: `./clients/opencode-mcp.json`
- Codex client: `./clients/codex-config.toml`

## Local Commands

```bash
sin-github-issues serve-a2a
sin-github-issues serve-mcp
sin-github-issues print-card
sin-github-issues run-action '{"action":"agent.help"}'
sin-github-issues run-action '{"action":"sin.github.issues.health"}'
sin-github-issues run-action '{"action":"sin.github.issues.auth.status"}'
sin-github-issues run-action '{"action":"sin.github.issues.profile.get"}'
sin-github-issues run-action '{"action":"sin.github.issues.profile.update","name":"Delqhi","company":"AIOMETRICS","blog":"https://www.delqhi.com"}'
sin-github-issues run-action '{"action":"sin.github.issues.profile.pinned_repos.list"}'
sin-github-issues run-action '{"action":"sin.github.issues.repo.metadata.update","repo":"owner/name","description":"...","topics":["ai","automation"]}'
sin-github-issues run-action '{"action":"sin.github.issues.achievement.quickdraw.trigger"}'
sin-github-issues run-action '{"action":"sin.github.issues.issue.ensure","repo":"owner/name","title":"Bug title","body":"..."}'
sin-github-issues run-action '{"action":"sin.github.issues.issue.evidence.policy"}'
sin-github-issues run-action '{"action":"sin.github.issues.repo.branch.start","repoPath":"/abs/repo","branchName":"fix/example"}'
sin-github-issues run-action '{"action":"sin.github.issues.runners.list","repo":"OpenSIN-AI/OpenSIN-backend"}'
sin-github-issues run-action '{"action":"sin.github.issues.workflow.runs.list","repo":"OpenSIN-AI/OpenSIN-backend","branch":"sin-github-issues-bootstrap"}'
sin-github-issues run-action '{"action":"sin.github.issues.workflow.local_suite.run","repoPath":"/abs/repo","suite":"docs-and-architecture","confirm":true}'
```

## Current Action Surface

### Issue & Repo Lifecycle

- `issue.ensure` / `issue.comment` / `issue.close`
- `issue.evidence.policy`
- `repo.status` / `repo.branch.start` / `repo.commit` / `repo.push`
- `workflow.finalize_fix` comment/closure handoff

### Issue Evidence Standard

- Use OpenCode `/share` links as the source of truth for issue evidence whenever a debugging or fix session exists.
- Put the share URL directly into the issue body or comment.
- Open that shared session in the browser and capture screenshots from the browser-rendered share page instead of from a local editor window.
- Always pair the share link and screenshot with exact `path:line` references.
- Keep the screenshot artifact in the issue timeline even if the backing session is later archived.

### Workflow & Runner Control

- `runners.list`
- `workflow.runs.list`
- `workflow.run.rerun`
- `workflow.run.cancel`
- `workflow.local_suite.run` for predefined local CI suites when GitHub-hosted Actions are unavailable or budget-blocked

### Profile & Achievement Management

- `auth.check` / `auth.login` guidance
- `profile.get` / `profile.update` (name, company, blog, location, bio, twitter, hireable)
- `profile.pinned_repos.list` / `profile.pinned_repos.set`
- `repo.description.update` / `repo.metadata.update`
- `achievement.quickdraw.trigger` / `achievement.quickdraw.status`

### Auth & Onboarding

- `auth.status` / `onboarding.status` / `onboarding.save`

## Publication Notes

- This package is Docker/Hugging Face Space ready via the repository `Dockerfile`.
- The standalone GitHub repo should contain the same contents as this directory root.
- Remote publication is only complete after landing, agent card, and A2A endpoint reachability are verified with the live audit.