GitHub Issues Projects and PRs

GitHub Issues, Projects, and PRs

Spec-Driven Develop can use GitHub as the execution tracker for large coding-agent work. When GitHub support is available, tasks become Issues, phases become Milestones, and task execution happens through branches, worktrees, and pull requests.

The workflow still works without GitHub. It falls back to local Markdown tracking when GitHub or the gh CLI is unavailable.

Tracking Modes

Mode	Requirements	Capabilities
GITHUB_FULL	gh CLI, authenticated GitHub access, project scope	Issues, Milestones, Labels, Project board, worktree, PR
GITHUB_STANDARD	gh CLI, authenticated GitHub access, repo scope	Issues, Milestones, Labels, worktree, PR
LOCAL_ONLY	No GitHub requirement	Local Markdown analysis, plan, and progress files

Pre-Flight Check

The workflow detects the best mode near the end of Phase 1.

gh --version > /dev/null 2>&1 || { echo "LOCAL_ONLY"; exit; }
gh auth status > /dev/null 2>&1 || { echo "LOCAL_ONLY"; exit; }
REPO=$(gh repo view --json nameWithOwner -q '.nameWithOwner' 2>/dev/null) || { echo "LOCAL_ONLY"; exit; }
gh issue list --repo "$REPO" --limit 1 > /dev/null 2>&1 || { echo "LOCAL_ONLY"; exit; }
gh project list --limit 1 > /dev/null 2>&1 && echo "GITHUB_FULL" || echo "GITHUB_STANDARD"

If project board access is missing, the workflow can still run in GITHUB_STANDARD mode.

Resource Mapping

Spec-Driven Develop run
├── Phase
│   └── GitHub Milestone
├── Task
│   └── GitHub Issue
├── Priority, size, phase, lane
│   └── GitHub Labels
├── Execution unit
│   └── Worktree + branch + PR
└── Completion
    └── PR merge closes Issue

Label Model

The workflow uses labels to make tasks filterable:

• spec-driven
• priority:P0, priority:P1, priority:P2
• size:S, size:M, size:L, size:XL
• phase:<number>
• lane:<letter>

Labels are created idempotently.

Issue Body Structure

Each task Issue should include:

• Task ID and title.
• Phase.
• Priority and size.
• Parallel lane.
• S.U.P.E.R drivers.
• Test expectation.
• Memory or governance impact.
• Description.
• Acceptance criteria.
• Affected files.
• Dependencies.

This structure keeps the Issue useful to both humans and agents.

Worktree and PR Execution

When a task starts, the agent reads the Issue, creates an isolated branch or worktree, implements the acceptance criteria, runs validation, and opens a PR linked to the Issue.

Typical branch pattern:

task/<issue-number>-<slug>

Typical PR body includes:

• Summary.
• closes #<issue-number>.
• Changes.
• S.U.P.E.R review.
• Tests.
• Governance or memory updates.

Cross-Session Continuity

In GitHub modes, docs/progress/MASTER.md is not the full task database. It is the local index.

The live task state is in GitHub:

• Issues show task status.
• Milestones show phase status.
• Project board shows workflow status when available.
• PRs show implementation history.
• Issue comments can store execution telemetry.

A new agent session should read MASTER.md and then query GitHub for live state because Issues may have closed after the last local update.

Related Pages

• Spec-Driven-Develop-Workflow
• Adaptive-Control-and-Drift-Score
• Project-Governance-and-Memory