Summary

Vigilante is currently GitHub-native end to end: watch targets assume GitHub repository slugs, issue intake and comment/PR maintenance live behind internal/github, prompts and operator workflows reference GitHub commands directly, and session state stores GitHub-specific metadata. We need an abstraction layer that lets Vigilante support additional project management systems such as Linear and Jira without rewriting the core orchestration loop each time.

A key requirement is that the backend used for issue tracking must be allowed to differ from the backend used for git remotes and pull-request management. For example, Vigilante should be able to take work from Linear or Jira while still cloning from GitHub and opening or maintaining GitHub pull requests.

Problem

• The current orchestration path treats GitHub as both the issue source and the operator surface, which makes the core scheduler, session lifecycle, and worktree logic harder to reuse for non-GitHub backends.
• Repo parsing, watch-target storage, issue selection, comment handling, resume/cleanup commands, and pull-request tracking are coupled to GitHub naming and APIs.
• The current model implicitly assumes a single system owns issue tracking, repository hosting, and PR lifecycle, which does not match common setups where work is tracked in Linear or Jira while source control and pull requests remain on GitHub.
• This blocks incremental support for systems like Linear or Jira, because adding a second project-management backend would require invasive changes across the app instead of plugging in a provider implementation.

Context

• README.md explicitly positions Vigilante as GitHub-native and describes GitHub issues as the work queue.
• internal/github/github.go owns issue listing, issue details/comments, rate limits, labels, and pull-request lookups.
• internal/repo/repo.go currently parses only GitHub remotes via ParseGitHubRepo.
• internal/state/state.go stores watch targets and session data using GitHub-centric fields such as Repo, IssueNumber, IssueURL, PullRequest*, and GitHub delay metadata.
• internal/app/app.go and internal/skill/skill.go reference GitHub-specific workflows directly, including vigilante gh issue comment, GitHub rate-limit handling, and GitHub-triggered resume / cleanup behavior.
• Today the code does not clearly separate:
  • the work-item system that provides issues/tasks and operator commands
  • the git hosting system that provides remote URLs and branch context
  • the pull-request system that provides review, mergeability, and merge actions
• The goal of this issue is to create the extensibility layer, not to fully ship production-ready Linear or Jira support in the same change.

Desired Outcome

• Vigilante has a provider abstraction for project-management backends that separates core orchestration from backend-specific issue/work-item APIs.
• Vigilante also models git remote hosting and pull-request management as concerns that can remain GitHub-backed even when the issue-tracking backend is something else.
• The existing GitHub behavior continues to work through a GitHub-backed implementation of that abstraction.
• The codebase has clear extension points for additional backends such as Linear and Jira, including provider-neutral concepts for watched targets, work items, comments/commands, and state transitions.
• It is possible for a watch target to represent combinations such as:
  • Linear issues + GitHub git remote + GitHub pull requests
  • Jira issues + GitHub git remote + GitHub pull requests
  • GitHub issues + GitHub git remote + GitHub pull requests
• Out of scope: fully implementing end-to-end Linear support, fully implementing end-to-end Jira support, or redesigning the coding-agent provider abstraction.

Implementation Notes

• Introduce a backend interface package for the project-management system layer. It should cover the minimum operations the orchestration loop needs, such as:
  • resolving a watch target / project identifier
  • listing eligible work items
  • fetching work-item details and comments
  • posting progress / blocker updates
  • reading operator-triggered iteration or cleanup commands
  • syncing managed state back to the issue-tracking backend when supported
• Do not assume the issue-tracking backend is also the git remote or pull-request backend. Model these separately so the orchestration layer can combine them.
• Keep GitHub as the first concrete implementation by adapting the current internal/github functionality behind the new interfaces instead of leaving GitHub-specific calls scattered through internal/app.
• Refactor provider-neutral types so the app loop does not depend on GitHub names where it does not need to. Examples:
  • prefer explicit backend identities plus backend-specific target references over a bare GitHub repo slug as the only watch-target identity
  • distinguish generic work-item metadata from git-host metadata and from PR metadata
  • isolate GitHub-only rate-limit or label behavior so other backends can opt in only where relevant
• Preserve the current user-facing GitHub workflow unless a behavior change is required to introduce the abstraction safely.
• It is acceptable to keep some GitHub-only capabilities behind optional interfaces or capability checks if other backends will not support them on day one.
• Update docs and terminology where needed so GitHub remains a supported backend, not the only conceptual model.

Acceptance Criteria

• The main orchestration loop no longer calls GitHub-specific issue APIs directly; it depends on a project-management backend abstraction instead.
• The design explicitly supports the issue-tracking backend being different from the git remote backend and the pull-request backend.
• The current GitHub behavior is preserved through a GitHub backend implementation, including issue selection, details/comments lookup, progress commenting, and existing maintenance flows that still apply.
• Watch-target and session models can represent backend identity separately for work-item tracking and for repository / pull-request hosting without assuming GitHub-only naming.
• GitHub-only behaviors such as rate-limit handling, label syncing, PR maintenance, and issue-comment commands are either isolated behind the GitHub backend or guarded by explicit capability checks.
• The abstraction is designed so a follow-up implementation can add Linear or Jira issue tracking on top of GitHub-hosted repositories and pull requests without restructuring the core dispatch/session lifecycle again.
• README and relevant command/help text are updated to describe Vigilante as extensible to multiple project-management backends while documenting GitHub as the only fully implemented backend if that remains true after the change.

Testing Expectations

• Add or update unit tests around the new backend abstraction and the GitHub-backed implementation.
• Update orchestration tests so they validate behavior through the abstraction rather than through direct internal/github calls.
• Cover regressions around existing GitHub workflows: issue selection filters, comment-driven resume/cleanup handling, label/state synchronization, and PR maintenance paths.
• Add tests that exercise mixed-backend modeling so configurations like Linear-or-Jira issue tracking plus GitHub remotes / PRs are representable even if non-GitHub issue execution is not fully implemented yet.
• Add tests for capability gating or backend selection so unsupported backend-specific behaviors fail clearly instead of silently breaking the loop.

Operational / UX Considerations

• Backward compatibility matters for existing watch targets and persisted sessions. If storage formats change, include a safe migration or compatibility path.
• Keep CLI and state terminology consistent enough that future Linear/Jira support can be added without another large rename pass.
• Preserve current GitHub operator commands and documentation where still applicable.
• If the abstraction introduces backend capability differences, surface them explicitly in logs/status output rather than silently skipping behavior.
• Be explicit in config and status output about which backend owns work-item tracking versus which backend owns git remotes and pull requests.