GitHub Issues and PRs Agent Workflow

Purpose

This document describes a future direction for using GitHub Issues and pull requests as an agent-readable task queue for Prox OS. It is a roadmap model, not a claim that full automation exists today.

Current Posture

Today, humans and AI agents can manually use issues, branches, worktrees, PR summaries, and quality checks. Human maintainers still own priority, review, merge, and release decisions.

Future Issue Shape

An agent-ready issue should include:

## Scope

## Allowed paths

## Forbidden paths

## Required reading

## Acceptance criteria

## Quality commands

## Conflict risk

## Human reviewer

Candidate Labels

area:docs
area:app
area:os-shell
area:api-worker
area:ui
risk:low
risk:medium
risk:high
agent-ready
human-review-required

Agent Execution Loop

Future local or cloud agents may:

Read an agent-ready issue.
Create a scoped branch and worktree.
Run the pre-flight impact check.
Implement only the allowed scope.
Run quality commands.
Open or update a PR.
Summarize changed files, risks, and follow-ups.

The human owner decides whether the work merges, needs revision, becomes a new issue, or changes the roadmap.

Automation Boundaries

Low-risk docs and isolated leaf app tasks are the best candidates for higher automation.

Do not auto-merge high-risk work:

App contract.
Window manager or shell runtime.
App registry composition.
Design tokens.
Root tooling.
Auth, billing, permissions, audit, legal, or compliance.
Database schema or migrations.
Deployment, domains, Access, secrets, or production environment changes.

PR Expectations

Agent-authored PRs should include the template from Branch and Merge Rules, plus a link to the source issue and any run log or integration report when applicable.