# Tkersey Dotfiles Join > Join - Skill: `tomevault-io/tkersey-dotfiles-join` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/tkersey-dotfiles-join` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/tkersey-dotfiles-join/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/tkersey-dotfiles-join --- # Join ## Intent Run a continuous PR operator using `gh` commands only. Keep PRs created, green, and merge-ready with minimal-incision fixes. Do not approve or merge PRs unless explicitly instructed by the user. ## Command boundary (hard rule) - Use only `gh` CLI commands (`gh pr`, `gh run`, `gh api`, `gh repo`). - Do not run `git` or any non-`gh` command. - If a required action cannot be completed with `gh` alone, apply `auto:hold` and leave a blocking comment. ## Quick start 1. Ensure `gh auth status` succeeds. 2. Ensure labels exist: `auto:manage`, `auto:hold`. 3. Start the monitor loop. ## Auth preflight (required) - Run these checks before any PR routing or mutation: - `gh auth status` - `gh repo view / --json nameWithOwner --jq .nameWithOwner` - If either check fails: - Fail fast for the current run. - Apply `auto:hold` on affected PRs (or emit hold outcome in cloud loop when no PR is selected yet). - Record reason as `auth_unavailable`. ## Label contract - `auto:manage`: opt-in to automation. - `auto:hold`: pause automation. Contributor guidance: - Add `auto:manage` to opt in. - Add `auto:hold` to stop the operator. ## PR creation policy (gh-only) - For every non-default branch discoverable via `gh api` without an open PR, create a PR. - Use the repo PR template if present; else use `assets/pr-template.md`. - Prefer `gh pr create --fill` and apply `auto:manage`. - Default to ready-for-review (no drafts unless configured). ## Operating mode Use one mode only: - `gh`-only remote mode: no local checkout assumptions and no local workspace mutations. ## Cloud Join operator (`$puff` + `seq -> join`) Use this when running Join as a cloud subagent loop: 1. Launch with `$puff` `join-operator`. 2. For each patch artifact, route by weighted manifest-first scoring (include PR file-path hydration via `gh pr view --json files`): `target_pr_hint` (+5.0), `touched_entities` overlap (+0..4.5), `changed_paths` overlap (+0..3.0), base-branch match (+1.5), and `issue_refs` (+0.5 each, max +1.0). Compute confidence as `min(0.99, (raw_score / 12.0) * risk_multiplier)` where `risk_multiplier={low:1.00, medium:0.95, high:0.80, critical:0.65}`. 3. If routing gates fail, run `$seq` first to recover intent/context. Routing gates are: confidence below effective threshold (`threshold * risk_threshold_multiplier` where `risk_threshold_multiplier={low:0.95, medium:1.00, high:1.15, critical:1.25}`), top-two score margin `< 0.75`, no entity/path/hint signal, manifest entities exist but no entity match, or `risk_level` is `high|critical`. 4. Then run `$join` for gh-only PR operations and CI/handoff behavior. Launch recipe: - `"$PUFF_SCRIPT" join-operator --env --repo --patch-inbox ` - Canary recipe (one bounded cycle): - `"$PUFF_SCRIPT" join-operator --env --repo --patch-inbox --canary` Cloud auth note: - In cloud environments, provide `GH_TOKEN` (or `GITHUB_TOKEN`) with repo-scoped permissions needed for join operations. ## Patch manifest contract Patch producers should emit a manifest that validates against: - `assets/cloud-join-manifest.schema.json` - `assets/cloud-join-manifest.example.minimal.json` (copy-ready minimal example) - `assets/cloud-join-manifest.example.full.json` (copy-ready full example) Required fields: - `patch_id` - `producer` - `repo` (`owner/repo`) - `base_branch` - `changed_paths` (non-empty) - `intent_summary` Optional routing hints: - `target_pr_hint` - `issue_refs` - `touched_entities` (array of objects with `entity`; optional `file` and `kind`) - `risk_level` (`low|medium|high|critical`) - `confidence` - `patch_file` ## Monitor loop Process PRs sequentially (blocking per PR on CI): 1. List open PRs: `gh pr list --state open --json number,title,headRefName,labels,isDraft`. 2. For each PR: - Skip if `auto:hold`. - Skip if not `auto:manage` and not agent-created. - If draft, mark ready: `gh pr ready `. - Keep the branch current with `gh pr update-branch --rebase` when available. - Enforce CI gate (required checks only; see below). - If failing, run the surgical fix loop. - When green, publish merge-ready handoff status. - Do not approve or merge. ## CI gate (required checks only) - Gate on required checks only (`gh pr checks --required`). Optional checks do not block handoff. - Detect “ungated” repos/PRs (no required checks): - If `gh pr checks --required --json name` returns an empty list, treat CI as green and proceed to handoff. - Wait for required checks (blocking): - `gh pr checks --required --watch --fail-fast` - This blocks until all required checks pass or the first required check fails. - Stalled CI (10 minutes with no observable progress): - Define “progress” as any change in the required-check snapshot (`name`, `bucket`, `startedAt`, `completedAt`). - While waiting, periodically sample: `gh pr checks --required --json name,bucket,startedAt,completedAt`. - If the snapshot does not change for 10 minutes while not all checks are `bucket=pass`, apply `auto:hold` and leave a summary comment with links to the stuck checks. - Treat `bucket=pending`, `bucket=skipping`, and `bucket=cancel` as “not green” (blocked) until resolved; do not mark as handoff-ready through them. - Drill into GitHub Actions when needed: - Identify check links: `gh pr checks --required --json name,bucket,link,workflow` - Find likely runs: `gh run list --branch --limit 10` - Watch a run live: `gh run watch --compact --exit-status` - Fetch failing step logs: `gh run view --log-failed` ## Surgical fix loop (gh-only) Smallest change that makes CI green using `gh` only: 1. Read the failure from CI logs. 2. Apply the minimal fix through GitHub APIs via `gh api` on the PR head branch. 3. Re-run checks and re-evaluate. 4. Apply a hard regression floor before each new attempt: - Snapshot required checks before and after each attempt (`gh pr checks --required --json name,bucket`). - If required checks get worse (for example: more failing checks, fewer passing checks, or a new blocked required check), stop immediately, apply `auto:hold`, and publish `hold_reason=regression_floor_worsened`. - If two consecutive attempts show no reduction in failing required checks, stop, apply `auto:hold`, and publish `hold_reason=regression_floor_no_improvement`. 5. Limit attempts (default 3). On exhaustion, permission issues, or hard conflicts: - Leave a summary comment. - Request changes as last resort. - Apply `auto:hold`. ## Handoff (no merge) - When required checks are green (or no required checks exist) and no hold: - Update status/comment to indicate: ready for human review/merge. - Keep the PR open. - Policy: - Never run `gh pr merge` (any flags). - Never run `gh pr review --approve` unless explicitly instructed by the user. - Confirm handoff state: - `gh pr view --json state,mergeStateStatus,reviewDecision` ## Adaptive polling - Poll under 60s unless CI is slow. - Use recent CI duration to back off (cap at 120s). - Exponential backoff on API errors. ## Status reporting - Maintain a single PR comment/check-run named `Join Operator`. - Update in place (avoid comment spam). - Include machine-checkable fields in each status update: - `raw_score` - `score_breakdown` (`target_pr_hint`, `entity_overlap`, `entity_hits`, `path_overlap`, `base_branch_match`, `issue_refs`, `risk_multiplier`) - `threshold_decision` (`confidence_threshold`, `effective_confidence_threshold`, `risk_threshold_multiplier`, `score_margin`, `needs_seq_reasons`) - `conflict_kind` (`none|routing|merge|policy|permission|ci`) - `complexity` (`low|medium|high`) - `confidence` (`0.00-1.00`) - `resolution_hint` (actionable next step; `none` only when resolved) - `action_taken` - `status` (`applied|hold|failed|no_match`) - `hold_reason` ## Gh-only block comment template ``` Join Operator: gh-only automation block This PR needs an action outside the gh-only boundary (for example, manual conflict resolution or a local-only edit path). Apply the needed commit manually, then remove `auto:hold`. ``` ## Stalled CI comment template ``` Join Operator: required checks stalled Required checks showed no progress for 10 minutes. Investigate the linked runs, unblock CI, then remove `auto:hold`. ``` ## Recipes (gh-only) - Default branch: `gh repo view --json defaultBranchRef --jq .defaultBranchRef.name` - Branch discovery: `gh api repos///branches --paginate --jq '.[].name'` - Create: `gh pr create --fill --head --label auto:manage` - Open PRs: `gh pr list --state open --json number,title,headRefName,labels,isDraft` - Mark ready: `gh pr ready ` - Update branch: `gh pr update-branch --rebase` - PR head OID: `gh pr view --json headRefOid --jq .headRefOid` - Required checks (summary): `gh pr checks --required` - Required checks (watch): `gh pr checks --required --watch --fail-fast` - Required checks (links/JSON): `gh pr checks --required --json name,bucket,link,workflow` - Actions runs (by branch): `gh run list --branch --limit 10` - Actions run logs: `gh run view --log-failed` - Request changes: `gh pr review --request-changes --body ""` - Handoff state: `gh pr view --json state,mergeStateStatus,reviewDecision` - Handoff note (example): `gh pr comment --body "Join Operator: required checks are green; ready for human merge."` ## Assets - `assets/pr-template.md` - `assets/cloud-join-manifest.schema.json` - `assets/cloud-join-manifest.example.minimal.json` - `assets/cloud-join-manifest.example.full.json` - `assets/cloud-join-operator-prompt.md` - `scripts/build_cloud_join_prompt.py` - `scripts/manifest_router.py` --- > Converted and distributed by [TomeVault](https://tomevault.io/claim/tkersey) — claim your Tome and manage your conversions.