9thlevelsoftware/legion/github-sync

GitHub Availability Check (run before ANY GitHub operation):
 
Step 1: Check gh CLI authentication
  Command: gh auth status 2>&1
  - If exit code 0: gh is authenticated, proceed
  - If non-zero: GitHub unavailable, skip all operations silently
 
Step 2: Check for GitHub remote
  Command: git remote get-url origin 2>/dev/null
  - If exit code 0: remote exists, proceed
  - If non-zero: no remote, skip all operations silently
 
Step 3: Get repo metadata (cache for session)
  Command: gh repo view --json nameWithOwner,defaultBranch -q '.nameWithOwner + " " + .defaultBranch'
  - Parse: REPO_SLUG = first token, DEFAULT_BRANCH = second token
  - Cache these values — do not re-query within the same command run
 
The result of this check is a boolean: github_available = true/false
All subsequent sections assume this check has been performed.
If github_available is false, the calling workflow skips the GitHub section entirely.

LEGION_LABEL = "legion"
LEGION_LABEL_COLOR = "7B68EE"
LEGION_LABEL_DESCRIPTION = "Created by Legion"
BRANCH_PREFIX = "legion/phase-"

Command: gh label create legion --description "Created by Legion" --color 7B68EE 2>/dev/null

Input: phase_number, phase_name, phase_goal, plans_list, requirements, success_criteria
Output: issue_number (integer)
 
Command:
  gh issue create \
    --title "Phase {phase_number}: {phase_name}" \
    --body "{ISSUE_BODY}" \
    --label "legion" \
    {--milestone "MILESTONE_TITLE" if a GitHub milestone exists for the current ROADMAP milestone}
 
ISSUE_BODY format:
  ## Goal
  {phase_goal}
 
  ## Plans
  - [ ] Plan {NN}-01: {plan_1_name}
  - [ ] Plan {NN}-02: {plan_2_name}
  - [ ] Plan {NN}-03: {plan_3_name}
 
  ## Requirements
  {requirement_ids, comma-separated}
 
  ## Success Criteria
  {success_criteria as bullet list}
 
  ---
  *Created by Legion*
 
Capture issue number:
  Parse the URL returned by gh issue create — the last path segment is the issue number.
  Example: https://github.com/user/repo/issues/42 → issue_number = 42
  Fallback: gh issue list --label legion --state open --json number,title -q '.[0].number'

Input: issue_number, comment_text
Command:
  gh issue close {issue_number} --comment "{comment_text}"

Phase completed successfully.
- Plans executed: {count}
- Requirements satisfied: {req_ids}
- Review result: {pass/escalated}

Step 1: Read current issue body
  Command: gh issue view {issue_number} --json body -q .body
 
Step 2: Find and update the plan checkbox
  - Locate the line: "- [ ] Plan {NN}-{PP}: {plan_name}"
  - Replace with: "- [x] Plan {NN}-{PP}: {plan_name}"
  - If the line is not found (already checked or not present): skip silently
 
Step 3: Write updated body
  Command: gh issue edit {issue_number} --body "{updated_body}"
 
Step 4: Verify (optional)
  - If the edit command succeeds (exit code 0): proceed
  - If it fails: log the error, continue the build — checklist update is cosmetic

Step 1: Check current branch
  Command: git branch --show-current
  - If result equals DEFAULT_BRANCH (from Section 1):
    Create feature branch: git checkout -b {BRANCH_PREFIX}{NN}-{slug}
    Example: git checkout -b legion/phase-03-phase-planning
    The slug is the phase name in kebab-case, truncated to 40 characters.
  - If result is NOT the default branch:
    Use the current branch as-is (the user or a previous workflow created it)
 
Step 2: Check for unpushed commits
  Command: git log origin/{current_branch}..HEAD --oneline 2>/dev/null
  - If the remote tracking branch doesn't exist: all local commits are unpushed
  - Count unpushed commits for the PR description
  - If zero unpushed commits: abort PR creation — nothing to submit
 
Step 3: Push to remote
  Command: git push -u origin {current_branch}
  - The -u flag sets upstream tracking for future pushes
  - If push fails: report error, do NOT create PR
  - Common push failures: permission denied, remote rejected, network error

Input: phase_number, phase_name, phase_goal, plan_summaries[], files_modified[],
       requirements[], issue_number (optional)
Output: pr_number, pr_url
 
Command:
  gh pr create \
    --title "Phase {phase_number}: {phase_name}" \
    --body "{PR_BODY}" \
    --base {DEFAULT_BRANCH}
 
PR_BODY format:
  ## Summary
  {phase_goal}
 
  ## Changes
  ### New Files
  - {new_file_1}
  - {new_file_2}
 
  ### Modified Files
  - {modified_file_1}
  - {modified_file_2}
 
  ## Plans Executed
  | Plan | Wave | Status | Summary |
  |------|------|--------|---------|
  | {NN}-01 | 1 | Pass | {one-line from SUMMARY.md} |
  | {NN}-02 | 1 | Pass | {one-line from SUMMARY.md} |
  | {NN}-03 | 2 | Pass | {one-line from SUMMARY.md} |
 
  ## Requirements Satisfied
  - {REQ-01}: {description}
  - {REQ-02}: {description}
 
  {If issue_number exists: "Closes #{issue_number}"}
 
  ---
  *Created by Legion*
 
Capture PR number:
  Parse from the gh pr create output URL.
  Example: https://github.com/user/repo/pull/15 → pr_number = 15

Input: milestone_name, milestone_description, phase_range (start-end)
Output: github_milestone_number
 
Step 1: Check if milestone already exists
  Command: gh api "repos/{REPO_SLUG}/milestones" --jq '.[].title'
  - If milestone_name is in the list: return its number, do not create a duplicate
  - To get the number of an existing milestone:
    gh api "repos/{REPO_SLUG}/milestones" --jq '.[] | select(.title == "{milestone_name}") | .number'
 
Step 2: Create milestone
  Command:
    gh api "repos/{REPO_SLUG}/milestones" \
      --method POST \
      -f title="{milestone_name}" \
      -f description="Phases {start}-{end}: {milestone_description}"
 
  Parse number from JSON response: .number
 
Step 3: Record in STATE.md
  - Add a row to the ## GitHub > ### Milestones table (see Section 6)
  - Store the GitHub milestone number for future reference

Input: github_milestone_number
 
Step 1: Verify all issues in milestone are closed
  Command: gh api "repos/{REPO_SLUG}/milestones/{github_milestone_number}" --jq '.open_issues'
  - If open_issues > 0: log warning "Milestone has {N} open issues" but proceed with close
    (The user may have added non-Legion issues to the milestone)
 
Step 2: Close the milestone
  Command:
    gh api "repos/{REPO_SLUG}/milestones/{github_milestone_number}" \
      --method PATCH \
      -f state=closed
 
Step 3: Update STATE.md
  - The milestone row status is NOT updated in STATE.md (status is fetched live)
  - See Section 6 for state linking rules

Step 1: Determine which ROADMAP milestone covers the current phase
  - Read ROADMAP.md milestone definitions
  - Find the milestone whose phase range includes the current phase number
 
Step 2: Check if that milestone exists on GitHub
  - Look up in STATE.md ## GitHub > ### Milestones table
  - If the milestone has a GitHub number: use it
  - If not: create the milestone first (Section 4.1), then use the new number