### Concrete Example of Minimized Plan

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/plan-deprecation.md

An example of a plan file after it has been minimized, showing the migrated status and a link to the canonical roadmap.

```markdown
# v2 Bundle redesign plan

> **Status:** Migrated to GitHub issues on 2026-04-26.
> **Canonical roadmap:** [Epic: v2 enhancements](https://github.com/ctxr-dev/agent-staff-engineer/issues/17).

This plan was migrated to a wired native sub-issue tree on https://github.com/orgs/ctxr-dev/projects/1. The full pre-migration content is recoverable from git history (`git log --all --source -- plans/v2-bundle.md` to find the pre-migration commit). Future planning lives in the issue tree; this file is kept only as a redirect for inbound links.
```

--------------------------------

### Install Agents using @ctxr/kit

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/agents-orchestration.md

Installs specified agents globally for use in any project session. Ensures agents are available everywhere.

```bash
npx @ctxr/kit@latest install --user @ctxr/agent-codebase-explorer @ctxr/agent-plan-reviewer @ctxr/agent-implementation-auditor
```

--------------------------------

### Clone and Build GitHub MCP Server

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/README.md

Use this method for offline installation or faster startup. It involves cloning the repository into a local directory, installing dependencies, and building the server.

```shell
grep -qxF '.tools/' .gitignore 2>/dev/null || printf '%s\n' '.tools/' >> .gitignore
git clone https://github.com/ctxr-dev/mcp-github .tools/mcp-github
( cd .tools/mcp-github && npm ci && npm run build )
```

--------------------------------

### Legacy Install Migration Commands

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/README.md

Commands to migrate from the old .claude/memory/ layout to the new .agents/ layout. Use plain 'mv' as the old paths were gitignored.

```shell
mkdir -p .agents/ctxr-dev
mv .claude/memory/ctxr-dev .agents/ctxr-dev/github-dev-methodology
mv .claude/memory/ctxr-dev.config.local.md .agents/ctxr-dev/github-dev-methodology.config.local.md
```

--------------------------------

### Install Locked Labels Across Repositories

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/label-taxonomy.md

This script iterates through specified repositories and installs locked labels using the 'gh label create' command. It reads label definitions from a YAML file and applies them forcefully, redirecting output to null.

```bash
# Install locked labels across every repo in the project:
for REPO in <REPO_1> <REPO_2> ...; do
  while IFS='|' read -r name desc color; do
    [ -z "$name" ] && continue
    gh label create "$name" --repo <OWNER>/$REPO --description "$desc" --color "$color" --force >/dev/null 2>&1
  done < <(npx --yes js-yaml templates/labels/default-taxonomy.yaml | jq -r '.locked[] | "\(.name)|\(.description)|\(.color)"')
done
```

--------------------------------

### Substitution Table Example

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/plan-to-issues.md

Maintain a running map of placeholders to real issue numbers for cross-referencing within issue bodies. This is crucial for ensuring sub-issue links are valid at creation time.

```text
<placeholder>           → real-issue-#
```

```text
EPIC                    → ?
```

```text
SUBSTRATE               → ?
```

```text
RUNNER                  → ?
```

```text
... (one per issue you'll create)
```

--------------------------------

### Run Validation Scripts

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/index.md

Execute validation scripts from the methodology directory. Ensure you have installed the necessary npm packages. Replace placeholders with your specific issue URLs, repository details, or file paths.

```bash
cd .agents/ctxr-dev/github-dev-methodology/scripts
npm install
node validate-tree.mjs <ROOT_ISSUE_URL>
```

```bash
node validate-issue-schema.mjs <OWNER>/<REPO>
```

```bash
node validate-labels.mjs <OWNER>
```

```bash
node diff-plan.mjs <PLAN_FILE> <PROJECT_URL>
```

--------------------------------

### Conventional Commit Example

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/commits.md

An example of a conventional commit message including type, scope, subject, body, and a footer to close an issue.

```git commit message
feat(pr-iteration): autonomous mode exit on reviewer + CI predicate

Implements the canonical loop exit per pr-loop.md: terminates iff every
required reviewer has approved-no-comments AND CI status is success. Falls
back to interactive mode when --interactive flag is set.

Closes: ctxr-dev/agent-staff-engineer#52
```

--------------------------------

### Bootstrap Canonical Labels

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/plan-to-issues.md

Installs canonical label families across all repositories contributing issues to the project. This ensures a consistent labeling system for issue types, scopes, and statuses.

```bash
for REPO in <REPO_1> <REPO_2> ...; do
  for label in \
    "type:epic|Umbrella parent issue with sub-issues|5319E7" \
    "type:feature|New capability|0E8A16" \
    "type:enhancement|Improvement to existing capability|0075CA" \
    "type:bug|Defect|D73A4A" \
    "type:refactor|Internal restructure, no behaviour change|1D76DB" \
    "type:docs|Documentation|0052CC" \
    "type:chore|Maintenance / infrastructure|C5DEF5" \
    "scope:breaking|Breaks backward compatibility|B60205" \
    "scope:additive|Additive only; no breaking change|E99695"; do
    name=${label%%|*}; rest=${label#*|}; desc=${rest%%|*}; color=${rest##*|};
    gh label create "$name" --repo <OWNER>/$REPO --description "$desc" --color "$color" --force >/dev/null 2>&1
  done
done
```

--------------------------------

### Detect Copilot Availability using GitHub API

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/commits.md

Uses the GitHub GraphQL API to check if Copilot is installed on a repository by looking for reviews from the 'copilot-pull-request-reviewer' bot. Caches the bot's node ID if found.

```bash
# Copilot is installed on a repo IFF a recent PR shows reviews authored by __typename "Bot" and login "copilot-pull-request-reviewer".
gh api graphql -f query='query($o:String!,$r:String!){repository(owner:$o,name:$r){pullRequests(first:5,states:[MERGED,OPEN]){nodes{reviews(first:5){nodes{author{__typename login ... on Bot{id}}}}}}}}' \
  -f o=<OWNER> -f r=<REPO> --jq '[.data.repository.pullRequests.nodes[].reviews.nodes[].author | select(.__typename == "Bot" and .login == "copilot-pull-request-reviewer")] | first | .id // "NOT_INSTALLED"'
```

--------------------------------

### Validate Issue Tree and Dependencies

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/cold-start.md

Verifies the upstream dependencies of an issue, ensuring that all 'Blocked by:' issues are closed and that the issue chain reaches the project root within four hops without cycles. This confirms the issue is ready to be started.

```bash
node scripts/validate-tree.mjs <OWNER>/<REPO>#<NUM>
```

--------------------------------

### Cold-Start Readiness Prompt Template

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/parallel-validation.md

This prompt template is for Agent 3, which assesses if issues are ready for a fresh agent with no prior context. It checks for clarity on 'why', 'what', 'how', and resolves cross-references.

```text
Spot-check 3-5 issues from the touched list. Imagine a fresh agent opens each one with zero prior context. Could they execute?

Touched issues to sample (pick 3-5; lean toward implementation issues, not epics):
- <OWNER>/<REPO>#<NUM>
- ...

For each sampled issue, score:
A. Could a fresh engineer extract: WHY this exists, WHAT done looks like, WHICH files to touch, WHAT blocks them, WHAT downstream depends?
B. Do all `#NN` cross-refs resolve to real issues?
C. Does the body follow the canonical schema (Metadata header + Why + Action items + Acceptance + Implementation pointers + Test plan)?
D. Are file paths concrete? Are tool names exact? No floating placeholders ("the audit report", "vX.Y.Z")?

Report (≤ 700 words): per-issue verdict (cold-start-ready: yes/no) + the strongest gap if any. End with: how many of N pass; common patterns of weakness; top 3 highest-leverage fixes.

Read-only.
```

--------------------------------

### Create AGENTS.md if it does not exist

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/README.md

Creates the AGENTS.md file with a predefined content if it does not exist. This is the entry point for AI coding agents.

```markdown
# AGENTS.md

Entry point for AI coding agents working in this project.

## Methodologies

- [ctxr-dev/github-dev-methodology](.agents/ctxr-dev/github-dev-methodology/index.md) - GitHub Issues + Projects workflow, PR loop, plan-to-issues, validation. **ALWAYS read first.**
```

--------------------------------

### Clone the methodology repository

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/README.md

Clones the github-dev-methodology into the .agents/ctxr-dev directory. Creates the directory if it does not exist. Only clones if the repository is not already present.

```sh
mkdir -p .agents/ctxr-dev
if [ ! -d .agents/ctxr-dev/github-dev-methodology/.git ]; then
  git clone https://github.com/ctxr-dev/github-dev-methodology.git \
    .agents/ctxr-dev/github-dev-methodology
fi
```

--------------------------------

### Get GitHub Issue Node ID

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/plan-to-issues.md

Retrieves the unique node ID for a given GitHub issue using the GraphQL API. This is a prerequisite for linking issues.

```bash
# Get node ID:
PID=$(gh api graphql -f query='query($o:String!,$r:String!,$n:Int!){repository(owner:$o,name:$r){issue(number:$n){id}}}' \
  -f o=<OWNER> -f r=<REPO> -F n=<PARENT_NUM> --jq '.data.repository.issue.id')
CID=$(gh api graphql -f query='query($o:String!,$r:String!,$n:Int!){repository(owner:$o,name:$r){issue(number:$n){id}}}' \
  -f o=<OWNER> -f r=<REPO> -F n=<CHILD_NUM> --jq '.data.repository.issue.id')
```

--------------------------------

### Register mcp-github MCP server

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/README.md

Registers the mcp-github MCP server using npx. This command fetches, builds, and runs the server on demand. It includes environment variables for authentication and tool denial.

```json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "github:ctxr-dev/mcp-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}",
        "MCP_GITHUB_DENY_TOOLS": "gh.pr_merge"
      }
    }
  }
}
```

--------------------------------

### Refresh GitHub CLI Authentication Scopes

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/index.md

Use this command to refresh your GitHub CLI authentication with the necessary scopes for the 'pr-only' preset. Ensure you have the GitHub CLI installed and are logged in.

```bash
gh auth refresh -h github.com -s repo,workflow
```

--------------------------------

### Create EPIC Stub

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/plan-to-issues.md

Creates the root epic issue with a placeholder body and title. The children list will be back-filled later, and the epic's URL is captured for the substitution table.

```bash
EPIC_URL=$(gh issue create --repo <OWNER>/<REPO> \
  --title "Epic: <Roadmap Title>" \
  --body "$(cat <<EOF
> **Status:** Stub — full body back-filled at Step 7 once all children exist.

## Mission
<one paragraph>

## Children
To be back-filled at Step 7.
EOF
)" \
  --label "type:epic,phase:<phase>,scope:additive" 2>&1 | tail -1)
echo "EPIC = $EPIC_URL"
```

--------------------------------

### Completeness Audit Prompt Template

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/parallel-validation.md

This prompt template is for Agent 1, which audits the completeness of issues created or modified during a migration. It checks for promised artifacts, missing labels, and required metadata fields.

```text
You are auditing a just-completed migration. Plan reference: <plan-file-path>.

Touched issues (DO NOT audit beyond this list):
- <OWNER>/<REPO>#<NUM> "<title>"
- <OWNER>/<REPO>#<NUM> "<title>"
- ...

For each touched issue:
1. Read it via `gh issue view <NUM> --repo <OWNER>/<REPO> --json title,body,labels,state`.
2. Cross-reference against the plan file: was this issue promised? Is its body content consistent with the plan's promised content?
3. Specifically check: missing labels, missing metadata header fields (Priority / Size / Status / Blocked-by / Blocks), missing sections (Why / Action items / Acceptance / Implementation pointers / Test plan).

Report (≤ 600 words):
- Issues with PASS (no gap).
- Issues with FAIL (specific gap; ≤ 1-line per issue).
- Plan-promised artefacts that don't exist in GH (most important — these are real gaps).

Read-only. No file edits.
```

--------------------------------

### Get Project Field IDs

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/plan-to-issues.md

Retrieves the IDs for fields within a GitHub project (e.g., Status, Priority, Size) using a GraphQL query. These IDs are needed for updating item field values and can be cached.

```bash
# Get field IDs once (cache):
gh api graphql -f query='{ organization(login: "<OWNER>") { projectV2(number: <PROJECT_NUM>) { fields(first: 30) { nodes { ... on ProjectV2SingleSelectField { id name options { id name } } } } } }'
```

--------------------------------

### Recovering Original Plan Content with Git

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/plan-deprecation.md

Commands to find the commit SHA of a pre-deletion plan file and then display its content at that revision.

```bash
# Find the pre-deletion commit:
git log --all --source -- <plan-file-path>

# Read the file at that revision:
git show <SHA>:<plan-file-path>
```

--------------------------------

### Validate and Cascade-Install Labels

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/label-taxonomy.md

These commands use a Node.js script to validate label configurations against a canonical set. The first command reports missing or drifted labels, while the second command attempts to fix these issues by cascade-installing the canonical set.

```bash
node scripts/validate-labels.mjs <OWNER>           # report missing or drifted labels
```

```bash
node scripts/validate-labels.mjs <OWNER> --fix     # cascade-install canonical set
```

--------------------------------

### Same-Repo Reference Pattern

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/issue-schema.md

Use this pattern for referencing issues within the same repository. A simpler `#<NUM>` is acceptable, but the full URL is richer in plain Markdown contexts.

```markdown
#<NUM>
```

```markdown
[#<NUM>](https://github.com/<OWNER>/<REPO>/issues/<NUM>)
```

--------------------------------

### Run PR Review Watch Script

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/pr-loop.md

Initiates the PR review watch process. Configure the repository, reviewers, required approvals, and polling interval. The script exits with 0 on success, or 2 if the maximum wait time is exceeded.

```bash
node scripts/pr-review-watch.mjs \
  --pr <OWNER>/<REPO>#$PR_NUM \
  --reviewer copilot --reviewer <human-login> \
  --required <human-login> \
  --interval ${PR_LOOP_POLL_SECONDS:-60}
```

--------------------------------

### Copy local config template

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/README.md

Copies the local configuration template to the project's configuration file if the configuration file is missing. This ensures a default configuration is available.

```sh
if [ ! -f .agents/ctxr-dev/github-dev-methodology.config.local.md ]; then
  cp .agents/ctxr-dev/github-dev-methodology/templates/config.local.md \
    .agents/ctxr-dev/github-dev-methodology.config.local.md
fi
```

--------------------------------

### Local Configuration Schema

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/local-config.md

This markdown schema defines the structure for the local configuration file. It includes sections for active projects, project-specific values, and reviewer configurations. Use this to set up your project's methodology behavior.

```markdown
# github-dev-methodology.config.local.md (gitignored)

## Active

| Key |
|---|---|
| `active_project` | <slug-of-a-Project-section-below> |

## Project: <slug-1>

### Features

| Feature |
|---|---|
| `pr_loop` | true |
| `copilot_review` | true |
| `conventional_commits` | true |
| `agents_orchestration` | true |
| `audit_vs_execute` | true |
| `issue_schema` | false |
| `issue_lifecycle` | false |
| `label_taxonomy` | false |
| `plan_to_issues` | false |
| `parallel_validation` | false |
| `plan_deprecation` | false |
| `cold_start` | false |
| `subagent_review` | false |

### Project values

| Key |
|---|---|
| `project_url` | https://github.com/orgs/<OWNER>/projects/<NUM>/views/1 |
| `org` | <OWNER> |
| `primary_repo` | <REPO> |
| `sibling_repos` | <REPO_2>, <REPO_3>, ... |

### Reviewer + PR-loop config

| Key |
|---|---|
| `reviewers` | comma-separated INDIVIDUAL reviewer logins watched on every PR: `copilot`, `<github-login>`. The watch matches review-author logins, so a `<team-slug>` is never tracked (it would stay pending forever): you may still request a team for review, but list the member logins you expect to review here. Value `ask` triggers the first-run discovery + multi-select (see "How the agent reads it"). |
| `required_reviewers` | subset of `reviewers` whose `APPROVED` gates the exit predicate (humans only; bots have no `APPROVED` state). May be empty. |
| `pr_loop_wait_for` | `any` (default) | `smart` | `all` | `quorum:N`. Selects which reviewer transitions wake the loop between cycles (does NOT relax the done predicate). |
| `copilot_bot_id` | BOT_kgDOXXXXXX (per-installation; discover via commits.md snippet) |
| `pr_loop_poll_seconds` | 60 (override the default 60s cadence) |
| `pr_loop_max_hours` | 24 (override default 24h max-no-progress) |

> **Legacy `default_reviewer` is still honored as a one-element fallback** when `reviewers` is empty (doc/agent contract; nothing in the parser reads it, so the agent applies the fallback). Prefer `reviewers`; migrate old configs by moving the single value into the `reviewers` set.

### Dev-loop modes

| Key |
|---|---|
| `default_dev_loop_mode` | autonomous | interactive | handoff |

### Plan-deprecation policy

| Key |
|---|---|
| `plan_post_migration` | minimize (default) | delete |

## Project: <slug-2>

... (duplicate the section above; H3 subsections are visual grouping only - the parser pulls keys from any table row under the `## Project: <slug>` H2)

```

--------------------------------

### Minimal Plan Skeleton for Deprecation

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/plan-deprecation.md

This is the 5-line skeleton that replaces the original plan file content after migration to GitHub issues. It serves as a redirect and points to the canonical roadmap.

```markdown
# <Original Plan Title>

> **Status:** Migrated to GitHub issues on <YYYY-MM-DD>.
> **Canonical roadmap:** [<Epic Title>](<epic-url>).

This plan was migrated to a wired native sub-issue tree on <PROJECT_URL>. The full pre-migration content is recoverable from git history at the pre-migration HEAD (`git log --all --source -- <plan-file-path>` to find the SHA). Future planning lives in the issue tree; this file is kept only as a redirect for inbound links.
```

--------------------------------

### Requesting Reviews via GitHub API (GraphQL)

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/pr-loop.md

Triggers reviews for a configured set of reviewers using GitHub's GraphQL API. This includes requesting reviews from bots (like Copilot) and individual human users. The `union:true` option adds reviewers without removing existing ones.

```bash
# 4. Trigger review for the WHOLE configured set. PREFER the gh_pr_request_reviews
#    MCP tool: it resolves logins to node ids (including the Copilot bot) and accepts
#    user_logins / team_slugs / bot_logins arrays in ONE call. No-MCP gh-CLI fallback
#    below: gh cannot pass a multi-value GraphQL list, so request each reviewer in a
#    SEPARATE union:true call (union ADDS without removing prior requests; do NOT
#    chain these mutations with && -- one bad id would abort the rest).
PR_NUM=<number>
PR_ID=$(gh api graphql -f query='query($o:String!,$r:String!,$n:Int!){repository(owner:$o,name:$r){pullRequest(number:$n){id}}}' \
  -f o=<OWNER> -f r=<REPO> -F n=$PR_NUM --jq '.data.repository.pullRequest.id')
COPILOT_ID=<BOT_kgDO... cached as copilot_bot_id, or discovered per commits.md>
# Copilot via botIds (REST silently no-ops on bots, so GraphQL is REQUIRED):
gh api graphql -f query='mutation($pid:ID!,$ids:[ID!]){requestReviews(input:{pullRequestId:$pid,botIds:$ids,union:true}){pullRequest{reviewRequests(first:1){totalCount}}}}' -f pid="$PR_ID" -f ids="$COPILOT_ID"
# Each human: resolve login -> User node id, then request via userIds (repeat per login):
HUMAN_ID=$(gh api graphql -f query='query($l:String!){user(login:$l){id}}' -f l=<human-login> --jq '.data.user.id')
gh api graphql -f query='mutation($pid:ID!,$ids:[ID!]){requestReviews(input:{pullRequestId:$pid,userIds:$ids,union:true}){pullRequest{reviewRequests(first:1){totalCount}}}}' -f pid="$PR_ID" -f ids="$HUMAN_ID"
```

--------------------------------

### View GitHub Issue Details

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/cold-start.md

Fetches detailed information about a specific GitHub issue, including its number, title, state, body, labels, and comments. This is the first step in understanding the issue's context.

```bash
gh issue view <NUM> --repo <OWNER>/<REPO> --json number,title,state,body,labels,comments
```

--------------------------------

### Discover Native Issue Types in an Organization

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/label-taxonomy.md

This command retrieves a list of all native Issue Types configured for a specific organization. Run this once per organization before mapping issue types.

```bash
gh api orgs/<ORG>/issue-types
```

--------------------------------

### Local Development: Testing and Linting

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/pr-loop.md

Ensures code passes local tests and linting checks before committing. This step is mandatory before proceeding.

```bash
# 1. Author + test
# ... edits ...
npm test && npm run lint               # must pass before commit
```

--------------------------------

### Create GitHub Issue

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/issue-lifecycle.md

Use this command to create a new GitHub issue with a predefined body structure. Ensure the issue body adheres to the issue schema for validation.

```bash
gh issue create --repo <OWNER>/<REPO> \
  --title "<type>(<scope>): <subject>" \
  --body "$(cat <<'EOF'\n## Context\nWhich symptom / log / observation triggered the work.\n\n## Root cause\nfile:line references and a short mechanism explanation.\n\n## Proposed fix\nTouch list and a \"why this is the right shape\" paragraph.\n\n## Verification\nHow we'll know it worked (manual repro, test added, log check).\n\n## Priority rationale\nbug vs latent vs tradeoff, and who is impacted.\nEOF
)"
```

--------------------------------

### Add @AGENTS.md import to CLAUDE.md

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/README.md

Ensures the CLAUDE.md file contains the '@AGENTS.md' line for Claude Code compatibility. Creates CLAUDE.md if necessary.

```sh
# This is a conceptual representation of the logic described in the text.
# Actual implementation would involve conditional checks and file operations.
# Example: if CLAUDE.md exists, append '@AGENTS.md' if not present.
# Example: if .claude/ exists, create CLAUDE.md with '@AGENTS.md'.
```

--------------------------------

### Refresh GitHub CLI Authentication Scopes (Full Preset)

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/index.md

Use this command to refresh your GitHub CLI authentication with the necessary scopes for the 'full' preset, including administrative scopes for organizational issue types. This assumes the user has the required permissions.

```bash
gh auth refresh -h github.com -s repo,workflow,project,read:org,admin:org
```

--------------------------------

### Update GitHub Dev Methodology

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/README.md

Navigate to the methodology directory and pull the latest changes to update. This command should be run in your project's root directory.

```bash
cd .agents/ctxr-dev/github-dev-methodology && git pull
```

--------------------------------

### Dependency Graph Validation Prompt Template

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/parallel-validation.md

This prompt template is for Agent 2, which validates the dependency graph of touched issues. It checks for cycles, orphans, mis-rooted leaves, and bidirectional consistency of blocking relationships.

```text
Validate the native sub-issue tree for the touched issues only.

Touched issues:
- <OWNER>/<REPO>#<NUM>
- ...

For each issue:
1. Walk the parent chain via GraphQL `Issue.parent` until null. Report the chain.
2. Verify: chain terminates at <ROOT_EPIC_URL> within ≤ 4 hops.
3. Detect cycles: same issue appears twice in the chain.
4. Detect orphans: issue has no parent AND isn't the root.

Also for each issue, check downstream:
- Pull `subIssues` via GraphQL.
- For each child, verify the child's `Blocked by:` body line cites this issue (bidirectional consistency).

Report (≤ 500 words): per-issue verdict (PASS / cycle / orphan / mis-rooted / asymmetric-block). Cite real issue numbers.

Read-only.
```

--------------------------------

### Trigger Copilot Review using GitHub GraphQL API

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/commits.md

Triggers a review request for Copilot using the GitHub GraphQL API. This method is necessary because the REST API does not support requesting reviews from bot accounts.

```bash
PR_NUM=<num>
PR_ID=$(gh api graphql -f query='query($o:String!,$r:String!,$n:Int!){repository(owner:$o,name:$r){pullRequest(number:$n){id}}}' \
  -f o=<OWNER> -f r=<REPO> -F n=$PR_NUM --jq '.data.repository.pullRequest.id')

gh api graphql -f query='mutation($pid:ID!,$bots:[ID!]!){requestReviews(input:{pullRequestId:$pid,botIds:$bots,union:true}){pullRequest{reviewRequests(first:10){nodes{requestedReviewer{__typename ... on Bot{login} ... on User{login}}}}}}}' \
  -f pid="$PR_ID" -f bots="$COPILOT_BOT_ID"
```

--------------------------------

### Closing an Issue on Creation for Audit Trail

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/issue-schema.md

When creating an issue for already shipped work, set status to 'Done', close it immediately, and add a comment referencing the PR and commit. Pre-check action items.

```bash
gh issue close <num> --reason completed --comment "Implemented in PR #N commit <sha>"
```

--------------------------------

### Re-request Reviews

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/pr-loop.md

Re-requests reviews for the entire configured set after a push. This ensures that all reviewers re-evaluate the latest code changes and their reviews are applied to the new HEAD. Use `union:true` to preserve previous requests.

```bash
# Same requestReviews mutation as step 4 above (userIds + teamIds + botIds); union:true preserves previous requests.
```

--------------------------------

### GitHub CLI Authentication and Branch Checkout

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/pr-loop.md

Confirms authentication status and checks out a new branch for development. Use conventional naming for branches.

```bash
# 0. Confirm auth + branch
gh auth status
git checkout -b <type>/<slug>          # e.g. fix/null-deref-in-x
```

--------------------------------

### Agent Orchestration Topology

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/agents-orchestration.md

Visual representation of the agent orchestration flow, showing the interaction between the User, Orchestrator, and various Subagents (Explorer, Plan, Implement, Review). Illustrates the 'self-contained brief' and 'capped report' communication pattern.

```mermaid
flowchart TD
  U[User] -- "task" --> O["Orchestrator<br/>holds: plan + decisions + compacted history<br/>does NOT do the deep work itself"]

  O -- "self-contained brief" --> E1["agent-codebase-explorer<br/>(fresh context)"]
  O -- "self-contained brief" --> E2["agent-codebase-explorer<br/>(fresh context)"]
  O -- "self-contained brief" --> P["Plan subagent<br/>(fresh context)"]
  O -- "self-contained brief" --> I["Implement subagent<br/>(fresh context)"]
  O -- "self-contained brief" --> R["Review subagent<br/>(fresh context)"]

  E1 -- "capped report" --> O
  E2 -- "capped report" --> O
  P  -- "capped design" --> O
  I  -- "diff + summary" --> O
  R  -- "verdict" --> O

  I -- "nested brief" --> N1["Nested subagent<br/>(same rules, recursive)"]
  N1 -- "capped report" --> I

  O -- "summary, next round" --> O
  O -- "final report" --> U
```

--------------------------------

### Refresh GitHub CLI Authentication with Required Scopes

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/label-taxonomy.md

Use this command to refresh your GitHub CLI authentication, ensuring all necessary scopes for the bootstrap process are included. This should be done once at the beginning of the bootstrap.

```bash
gh auth refresh -h github.com -s read:org,admin:org,project,workflow,admin:repo_hook,admin:org_hook,repo
```

--------------------------------

### Run Validation Scripts

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/plan-to-issues.md

Executes a suite of validation scripts to ensure the integrity and consistency of the issue hierarchy and project board. All scripts must pass for the migration to be considered complete.

```bash
cd .agents/ctxr-dev/github-dev-methodology/scripts
node validate-tree.mjs <ROOT_EPIC_URL>            # parent chain reaches root
node validate-issue-schema.mjs <OWNER>/<REPO>     # body shape per issue
node validate-labels.mjs <OWNER>                  # label consistency cross-repo
node diff-plan.mjs <PLAN_FILE> <PROJECT_URL>      # plan vs actual project state
```

--------------------------------

### Pushing Changes and Creating a Pull Request

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/pr-loop.md

Pushes the current branch to the remote repository and creates a new pull request with a title and detailed body content. The body includes a summary and test plan.

```bash
# 3. Push + open PR
git push -u origin "$(git branch --show-current)"
gh pr create \
  --repo <OWNER>/<REPO> \
  --title "..." \
  --body "$(cat <<'EOF'
## Summary
...

## Test plan
- [ ] ...
EOF
)"
```

--------------------------------

### Cross-Repo Reference Pattern

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/issue-schema.md

Use this pattern for referencing issues in other repositories. GitHub automatically renders these as clickable links.

```markdown
<OWNER>/<REPO>#<NUM>
```

--------------------------------

### Add Local Configuration to .gitignore

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/local-config.md

Ensures that local configuration files and cloned methodology repositories are not tracked by Git. This maintains privacy and prevents accidental commits of sensitive or project-specific settings.

```gitignore
.agents/ctxr-dev/github-dev-methodology
*.local.md
```

--------------------------------

### GraphQL Query for Latest Reviews and Threads

Source: https://github.com/ctxr-dev/github-dev-methodology/blob/main/pr-loop.md

Use this GraphQL query to fetch the latest reviews and review threads for a pull request. This is crucial for determining reviewer status and identifying unresolved issues.

```graphql
latestReviews(first:100) { nodes { author { login } state commit { oid } } }
reviewThreads(first:100) { nodes { isResolved isOutdated comments(first:1) { nodes { author { login } } } } }
```