RFC: GitHub Issues Integration - Hooks & Adapters

[a4og5n]

RFC: GitHub Issues Integration - Hooks & Adapters

Problem Statement

I'm building a Next.js application where GitHub Issues is the single source of truth for project tracking.
We use:

• Epics (parent issues) for feature groupings
• Sub-issues for individual tasks
• Milestones for phase tracking
• Labels for metadata (type, area, priority, phase)
• GitHub Actions for automation

We've built custom scripts that handle issue creation, PR workflows, and enforce our metadata requirements.
However, maintaining these scripts is ongoing work, and we'd love to align with OpenSpec's structured approach.

The challenge: OpenSpec's artifact workflow (proposal → specs → design → tasks) is exactly what we need for planning, but we need those artifacts to flow into GitHub Issues rather than remaining as local files.

Use Case

Our current workflow:

1. Create planning document (markdown)
2. Convert to GitHub Epic + Sub-issues (via custom scripts)
3. Work issue-by-issue
4. GitHub is always the source of truth

What we'd like with OpenSpec:

1. /opsx:new → create structured artifacts
2. /opsx:ff → generate proposal, specs, design, tasks
3. New: Export to GitHub → Epic from proposal, sub-issues from tasks
4. GitHub becomes source of truth, OpenSpec artifacts can be deleted/archived

Proposed Approach

1. Event/Hook System

Allow users to run custom code on OpenSpec lifecycle events:

openspec/config.yaml

hooks:
  onCreate: "./scripts/on-create.sh"
  onArchive: "./scripts/on-archive.sh"
  # or TypeScript
  onArchive: "./scripts/hooks.ts#onArchive"

This would enable integrations without modifying OpenSpec core.

2. GitHub Adapter (Optional Built-in)

A configurable adapter that creates GitHub Issues from artifacts:

integrations:
  github:
    enabled: true
    repo: owner/repo  # or auto-detect from git remote
    epic_from: proposal  # which artifact becomes the epic
    issues_from: tasks   # which artifact becomes sub-issues
    labels:
      defaults: ["status:ready"]
    create_branch: true

3. CLI Command

openspec export github --change my-feature
# Creates epic + sub-issues, optionally creates branch

What I'm Offering

I have working bash scripts that do this today:

• Issue creation with full metadata (labels, milestone, assignee, project board)
• GraphQL mutations for sub-issue relationships
• PR creation with template compliance
• Branch management and cleanup

I'm willing to:

1. Generalize these into a TypeScript implementation
2. Build this as a standalone package first (openspec-github-bridge)
3. Contribute upstream if the approach aligns with OpenSpec's direction

Open Questions

1. Does this fit with the plugin architecture being discussed in Enhancement: Plugins #453? Should this be a plugin vs core feature?
2. Hook system design: Should hooks be config-based (yaml) or code-based (TypeScript config file)? Or both?
3. Abstraction level: Should GitHub be a specific adapter, or should there be a generic "issue tracker" interface that supports GitHub, Linear, Jira, etc.?
4. Source of truth: Once exported to GitHub, should OpenSpec track that relationship? Or is it a one-way export where GitHub becomes authoritative?
5. Existing work: Is anyone already building this? I saw Ecosystem & Integration #436 requests similar functionality - happy to collaborate.

Related

• Issue #436: Ecosystem & Integration
• Issue #453: Plugin System

Looking forward to feedback. Happy to iterate on the approach based on maintainer guidance.