Full Path Orchestrator (GitHub)

Confidence-gated pipeline. Takes a GitHub issue (raw or groomed) and delivers a reviewed, tested pull request. Stops only when it genuinely can't proceed — otherwise makes decisions, documents them, and moves on.

This is a personal-projects orchestrator: assumes one repo owner (you), no SLA, the gh CLI for all GitHub interaction, and the ~/workspace/ worktree convention — worktrees live in a sibling ~/workspace/{project}_workspace/ directory, named {project}-{slug}, on a build-{slug} branch (see Input and EXECUTE).

Intent Detection

Input

Prerequisites

Skills (at ~/workspace/skills/ or installed via install.sh)

Tools

Verify before starting:

gh auth status
ls ~/workspace/skills/{grill-me,structured-backlog,tdd-pocock,code-review,gh-pr-create}/SKILL.md

Sub-Skills

This orchestrator is a thin conductor. All phase logic lives in composable sub-skills under phases/. Read them in order as each phase begins:

full-path-github/
├── SKILL.md          # This file
└── phases/
    ├── guardrails.md  # READ FIRST — hard rules, confidence thresholds
    ├── intake.md      # Phase 1 — read issue, find code context
    ├── enrich.md      # Phase 2 — grill-me self-interrogation, pattern eval
    ├── plan.md        # Phase 3 — structured-backlog decomposition
    ├── execute.md     # Phase 4 — TDD loop via tdd-pocock
    ├── validate.md    # Phase 5 — tests + ACs + review rubric
    ├── ship.md        # Phase 6 — PR creation, execution log
    └── retrospect.md  # Phase 7 — friction analysis, skill creation

GitHub State Model (no state:: labels)

Personal projects don't need a six-state Kanban. The orchestrator uses three signals that are native to GitHub:

Add a single optional label orchestrator-blocked only when the orchestrator needs human input mid-flight. The presence of that label is the only "blocked-on-human" signal — its absence means work continues.

Native dependencies & sub-issues (work-ordering signals)

GitHub provides two native relationships the orchestrator respects (GA 2025):

These differ from orchestrator-blocked (which is "blocked on a human"). blocked_by is "blocked on other work" — INTAKE's dependency gate refuses to start an issue with open blockers (see intake.md Step 1.5), and SHIP reports which downstream issues a merge will unblock (ship.md Step 6.5).

Gotcha: both POST bodies take an integer id (-F, not -f). The string form silently no-ops. Reads are eventually-consistent — trust the dependencies/blocked_by list over the summary count when they disagree.

Create the label once in the repo:

gh label create orchestrator-blocked --description "Full-path orchestrator blocked on human input" --color B60205 --force

Workflow

Issue URL + Project
  │
  ├─ 0. Read guardrails.md                    ── Always first
  │
  ├─ 1. INTAKE (intake.md)                    ── assign issue to me
  │     Fetch issue, find code context,
  │     dependency gate (skip if blocked_by open),
  │     vagueness gate (what/where/verify)
  │     → blocked if too vague OR has open blockers
  │
  ├─ 2. ENRICH (enrich.md)                    ── update issue body
  │     Pattern quality evaluation
  │     Grill-me self-interrogation
  │     Confidence-gated decisions
  │     → blocked if low-confidence (plan-first/auto mode)
  │
  ├─ 3. PLAN (plan.md)
  │     E2E hook check (build if missing)
  │     Structured-backlog decomposition
  │     Parallel group identification
  │
  ├─ 4. EXECUTE (execute.md)                  ── follow tdd-pocock per task
  │     Worktree set up via scaffold-workspace (if not already)
  │     Vertical-slice TDD: test→impl→test→impl
  │     Parallel groups via subagents (optional)
  │
  ├─ 5. VALIDATE (validate.md)
  │     Layer 1:   Tests pass
  │     Layer 1.5: Schema-refutation (refute-first; external-contract code)
  │     Layer 2:   ACs verified
  │     Layer 3:   code-review ≥ Solid
  │     Layer 4:   E2E hooks pass (if applicable)
  │     → blocked if validation fails after retry
  │
  ├─ 6. SHIP (ship.md)                        ── draft PR → ready for review
  │     Push branch, create draft PR (gh-pr-create)
  │     Execution log in PR description
  │     Mark PR ready when validation green
  │
  └─ 7. RETROSPECT (retrospect.md)
        Analyze session friction
        Create skills for gaps found
        Write implementable refactor plans

Execution

Fresh Start

1. Read phases/guardrails.md
2. Read phases/intake.md — execute it
3. Read phases/enrich.md — execute it
4. Read phases/plan.md — execute it
5. Read phases/execute.md — execute it
6. Read phases/validate.md — execute it
7. Read phases/ship.md — execute it
8. Read phases/retrospect.md — execute it

At each phase transition, append to the execution log (a markdown buffer the orchestrator carries through the run, embedded in the PR description at SHIP time).

Resume After Block

When the user says "resume the orchestrator on issue #NNN":

1. Fetch the issue: gh issue view NNN --json title,body,labels,comments
2. Read the latest comment to find the human's response to the blocking question
3. Look at whether a draft PR exists to know how far along the run got
4. Read phases/guardrails.md
5. Read the sub-skill for the blocked phase
6. Continue from where the phase stopped, incorporating the human's input
7. Remove the orchestrator-blocked label

Resume mapping

Mode Reference

Error Handling

Output

When complete, report:

Full-path orchestrator complete.

  Issue:     {repo}#{number} — {title}
  PR:        {pr_url}
  Branch:    {branch_name}
  Worktree:  {worktree_path}

  Tasks:     {completed}/{total}
  Tests:     {pass_count} passing ({new_count} new)
  ACs:       {covered}/{total} verified
  Review:    {band} ({pct}%)
  E2E:       {pass/fail/n/a}

  Decisions: {high_count} high, {medium_count} medium (flagged)
  Blocks:    {block_count} encountered, {resolved_count} resolved

  Retrospect:
    Skills created:     {count}
    Refactors proposed: {count}

Review the PR when ready.

Composition

This skill composes other skills — each remains usable independently:

grill-me ─────────────┐
code-review ──────────┤
structured-backlog ───┤── full-path-github ──▶ PR
tdd-pocock ───────────┤
gh-pr-create ─────────┘
scaffold-workspace ──── (optional, for worktree setup)

Predecessor

A GitHub issue exists (raw or groomed). For personal projects this is typically your own brain dump — a sentence or two is fine; INTAKE will flag if it's too vague to proceed.

Successor

You review the PR. The orchestrator's execution log in the PR description provides full context for self-review.

Origin

Adapted from a private GitLab-flavored orchestrator. The TDD inner loop in EXECUTE delegates to the tdd-pocock skill (Matt Pocock's TDD skill, MIT-licensed, redistributed in this repo with attribution).