| resources | [{"path":"scripts/github_api.py","kind":"script","description":"Shared body-safe GitHub API transport, terminal envelope, legacy failure classifier, GraphQL operation context, and rate-limit metadata layer."},{"path":"scripts/github_read.py","kind":"script","description":"Shared paged REST readers, including the automation-only sanitized secret-scanning status signal."},{"path":"scripts/gh-pr.py","kind":"script","description":"REST-first pull request helper for PR view, list, create, edit, comment, checks, merge, supersede, and rate-limit operations."},{"path":"scripts/reconcile-runtime-checkout.py","kind":"script","description":"Safely fast-forward a runtime-bound checkout after a confirmed repository landing while preserving remote/local outcome separation."},{"path":"scripts/gh-issue","kind":"script","description":"Safe issue create, edit, and close helper for multiline Markdown bodies."},{"path":"scripts/gh-comment","kind":"script","description":"Safe stdin-backed comment helper for issues and pull requests."},{"path":"scripts/gh-with-env-token","kind":"script","description":"GitHub CLI wrapper that selects configured automation auth and refuses active-auth fallback unless explicitly allowed."},{"path":"scripts/git-commit-as-bot","kind":"script","description":"Commit with the configured automation author and committer identity."},{"path":"scripts/git-push-as-bot","kind":"script","description":"Push GitHub branches with the configured automation token."},{"path":"scripts/github-ci-diagnose.py","kind":"script","description":"Diagnose failing PR checks and summarize relevant CI log excerpts."},{"path":"scripts/github_workflow_babysit.py","kind":"script","description":"Dispatch or watch one exact GitHub Actions run with bounded protected-environment diagnosis and split-identity approval."},{"path":"scripts/github-repo-snapshot.sh","kind":"script","description":"Capture compact repository, branch, PR, and workflow state for orientation."},{"path":"scripts/github-work-evidence.py","kind":"script","description":"Collect bounded read-only cross-repo GitHub work evidence as JSON for planning, readiness, closeout, or LLM-led reporting."},{"path":"scripts/gh-plan.py","kind":"script","description":"Shared planning issue and Project helper used by GitHub planning workflows."},{"path":"references/repo-workflow.md","kind":"reference","description":"Detailed GitHub workflow, PR, checks, review, and cleanup guidance."},{"path":"references/cli-reference.md","kind":"reference","description":"GitHub helper command reference."},{"path":"references/issue-templates.md","kind":"reference","description":"Issue and planning body templates."},{"path":"references/config-schema.md","kind":"reference","description":"Repository GitHub metadata schema reference."},{"path":"references/github-projects.md","kind":"reference","description":"GitHub Projects configuration and field reference."},{"path":"references/work-evidence.md","kind":"reference","description":"Contract for the read-only GitHub work evidence helper and downstream consumers."},{"path":"references/operation-matrix.toml","kind":"reference","description":"Machine-readable transport, quota, actor, retry, and reconciliation decisions for GitHub helper operations."}] |
| commands | [{"name":"github-api-call","source":"skill","resource_path":"scripts/github_api.py","example_argv":["uv","run","scripts/github_api.py","call","--method","GET","/rate_limit"],"purpose":"Runs one body-safe GitHub API request and emits the versioned diagnostics envelope."},{"name":"github-api-rate-limit","source":"skill","resource_path":"scripts/github_api.py","example_argv":["uv","run","scripts/github_api.py","rate-limit"],"purpose":"Reads and normalizes GitHub rate-limit metadata through the shared API layer."},{"name":"github-secret-scanning-status","source":"skill","resource_path":"scripts/github_read.py","example_argv":["uv","run","scripts/github_read.py","--repo","OWNER/REPO","secret-scanning-status"],"purpose":"Reports clean, findings, unavailable, or not-enabled secret-scanning status without returning detected secret values or changing actor identity."},{"name":"github-pr-view","source":"skill","resource_path":"scripts/gh-pr.py","example_argv":["scripts/gh-pr.py","view","<pr>"],"purpose":"Reads pull request metadata through the REST-first helper."},{"name":"github-pr-create","source":"skill","resource_path":"scripts/gh-pr.py","example_argv":["scripts/gh-pr.py","create","--title","<title>","--body-file","<file>"],"purpose":"Creates pull requests through the helper with safe body handling."},{"name":"github-pr-checks","source":"skill","resource_path":"scripts/gh-pr.py","example_argv":["scripts/gh-pr.py","checks","<pr>"],"purpose":"Reads PR check runs and commit statuses through the helper."},{"name":"github-pr-merge","source":"skill","resource_path":"scripts/gh-pr.py","example_argv":["scripts/gh-pr.py","merge","<pr>","--method","merge","--delete-branch"],"purpose":"Merges pull requests through the helper with normalized defaults."},{"name":"github-reconcile-runtime-checkout","source":"skill","resource_path":"scripts/reconcile-runtime-checkout.py","example_argv":["uv","run","scripts/reconcile-runtime-checkout.py","--merged-worktree",".","--repo","OWNER/REPO","--landing-sha","<full-landing-sha>"],"purpose":"Reconciles a runtime-bound checkout from landed repo-local source without switching, stashing, resetting, or overwriting unsafe local state."},{"name":"github-issue-create","source":"skill","resource_path":"scripts/gh-issue","example_argv":["github/scripts/gh-issue","create","<title>","--repo","OWNER/REPO"],"purpose":"Creates GitHub issues by reading Markdown from stdin; pass the body with shell redirection or a quoted heredoc."},{"name":"github-issue-edit","source":"skill","resource_path":"scripts/gh-issue","example_argv":["github/scripts/gh-issue","edit","<issue>","--repo","OWNER/REPO"],"purpose":"Edits GitHub issues by reading replacement Markdown from stdin; pass the body with shell redirection or a quoted heredoc."},{"name":"github-issue-close","source":"skill","resource_path":"scripts/gh-issue","example_argv":["github/scripts/gh-issue","close","<issue>","--repo","OWNER/REPO","--reason","completed"],"purpose":"Closes GitHub issues by reading an optional close comment from stdin; pass the comment with shell redirection or a quoted heredoc."},{"name":"github-issue-reopen","source":"skill","resource_path":"scripts/gh-issue","example_argv":["github/scripts/gh-issue","reopen","<issue>","--repo","OWNER/REPO"],"purpose":"Reopens GitHub issues by reading an optional reopen comment from stdin; pass the comment with shell redirection or a quoted heredoc."},{"name":"github-comment","source":"skill","resource_path":"scripts/gh-comment","example_argv":["scripts/gh-comment","pr","<pr>"],"purpose":"Posts issue or PR comments through configured automation auth using stdin-backed Markdown."},{"name":"github-gh-with-env-token","source":"skill","resource_path":"scripts/gh-with-env-token","example_argv":["scripts/gh-with-env-token","api","user","--jq",".login"],"purpose":"Routes unsupported gh commands through configured automation auth and fails closed without changing actor unless fallback is explicitly allowed."},{"name":"github-git-commit-as-bot","source":"skill","resource_path":"scripts/git-commit-as-bot","example_argv":["scripts/git-commit-as-bot","-m","fix: describe change"],"purpose":"Commits with the configured automation identity as author and committer while preserving normal git commit flags."},{"name":"github-git-push-as-bot","source":"skill","resource_path":"scripts/git-push-as-bot","example_argv":["scripts/git-push-as-bot","-u","origin","task-branch"],"purpose":"Pushes GitHub branches using the configured automation token while restoring the normal remote URL afterward."},{"name":"github-ci-diagnose","source":"skill","resource_path":"scripts/github-ci-diagnose.py","example_argv":["uv","run","scripts/github-ci-diagnose.py","--pr","<pr>"],"purpose":"Diagnoses PR checks through shared REST readers, summarizes relevant job logs, and reports quota or degraded components explicitly."},{"name":"github-workflow-babysit","source":"skill","resource_path":"scripts/github_workflow_babysit.py","example_argv":["uv","run","scripts/github_workflow_babysit.py","dispatch","--repo","OWNER/REPO","--workflow","operator.yml","--ref","main","--approve-environment","protected-admin"],"purpose":"Dispatches with configured automation auth, captures the exact returned run id, diagnoses waiting runs immediately, and approves only explicitly authorized environments with the active human account."},{"name":"github-repo-snapshot","source":"skill","resource_path":"scripts/github-repo-snapshot.sh","example_argv":["scripts/github-repo-snapshot.sh","--json"],"purpose":"Captures compact local-git and paged REST GitHub state with per-component request, quota, and degradation evidence."},{"name":"github-work-evidence","source":"skill","resource_path":"scripts/github-work-evidence.py","example_argv":["uv","run","scripts/github-work-evidence.py","--repo","OWNER/REPO","--window","24h"],"purpose":"Collects JSON-only GitHub work evidence across repositories, subjects, releases, workflow runs, and mechanical buckets."}] |
| policy | {"command_policies":[{"id":"prefer-gh-pr-create-helper","match":{"argv_prefix":["gh","pr","create"]},"action":"require_preferred","message":"Raw `gh pr create` uses the active local GitHub account and is fragile for multiline Markdown. Use the GitHub helper-backed PR create path.","preferred":[{"kind":"script","path":"scripts/gh-pr.py","example_argv":["scripts/gh-pr.py","create","--title","<title>","--body-file","<file>"],"purpose":"Creates PRs through the configured automation token and preserves body formatting."}]},{"id":"prefer-gh-pr-edit-helper","match":{"argv_prefix":["gh","pr","edit"]},"action":"require_preferred","message":"Raw `gh pr edit` uses the active local GitHub account and can mangle body text. Use the GitHub helper-backed PR edit path.","preferred":[{"kind":"script","path":"scripts/gh-pr.py","example_argv":["scripts/gh-pr.py","edit","<pr>","--body-file","<file>"],"purpose":"Edits PR metadata or body through the configured automation token and safe body-file handling."}]},{"id":"prefer-gh-pr-comment-helper","match":{"argv_prefix":["gh","pr","comment"]},"action":"require_preferred","message":"Raw `gh pr comment` is easy to quote incorrectly and may use the active local account. Use the GitHub helper-backed PR comment path.","preferred":[{"kind":"script","path":"scripts/gh-pr.py","example_argv":["scripts/gh-pr.py","comment","<pr>","--body-file","<file>"],"purpose":"Posts PR comments with safe Markdown/body-file handling."},{"kind":"script","path":"scripts/gh-comment","example_argv":["scripts/gh-comment","pr","<pr>"],"purpose":"Reads comment Markdown from stdin and posts it safely."}]},{"id":"prefer-gh-pr-review-wrapper","match":{"argv_prefix":["gh","pr","review"]},"action":"require_preferred","message":"Raw `gh pr review` uses the active local GitHub account. Use the automation-token wrapper so review submissions are owned by the configured automation identity.","preferred":[{"kind":"script","path":"scripts/gh-with-env-token","example_argv":["scripts/gh-with-env-token","pr","review","<pr>","--body-file","<file>"],"purpose":"Posts PR reviews through the configured automation token and fails closed for writes if bot auth is unavailable."}]},{"id":"prefer-gh-pr-state-wrapper","match":{"argv_prefix":["gh","pr","close"]},"action":"require_preferred","message":"Raw PR state mutations use the active local GitHub account. Use the automation-token wrapper so PR state changes are owned by the configured automation identity.","preferred":[{"kind":"script","path":"scripts/gh-with-env-token","example_argv":["scripts/gh-with-env-token","pr","close","<pr>"],"purpose":"Mutates PR state through the configured automation token and fails closed for writes if bot auth is unavailable."}]},{"id":"prefer-gh-pr-reopen-wrapper","match":{"argv_prefix":["gh","pr","reopen"]},"action":"require_preferred","message":"Raw PR state mutations use the active local GitHub account. Use the automation-token wrapper so PR state changes are owned by the configured automation identity.","preferred":[{"kind":"script","path":"scripts/gh-with-env-token","example_argv":["scripts/gh-with-env-token","pr","reopen","<pr>"],"purpose":"Reopens PRs through the configured automation token and fails closed for writes if bot auth is unavailable."}]},{"id":"prefer-gh-pr-ready-wrapper","match":{"argv_prefix":["gh","pr","ready"]},"action":"require_preferred","message":"Raw PR readiness mutations use the active local GitHub account. Use the automation-token wrapper so PR state changes are owned by the configured automation identity.","preferred":[{"kind":"script","path":"scripts/gh-with-env-token","example_argv":["scripts/gh-with-env-token","pr","ready","<pr>"],"purpose":"Marks PRs ready through the configured automation token and fails closed for writes if bot auth is unavailable."}]},{"id":"prefer-gh-pr-update-branch-wrapper","match":{"argv_prefix":["gh","pr","update-branch"]},"action":"require_preferred","message":"Raw PR branch updates use the active local GitHub account. Use the automation-token wrapper so branch updates are owned by the configured automation identity.","preferred":[{"kind":"script","path":"scripts/gh-with-env-token","example_argv":["scripts/gh-with-env-token","pr","update-branch","<pr>"],"purpose":"Updates PR branches through the configured automation token and fails closed for writes if bot auth is unavailable."}]},{"id":"prefer-gh-pr-merge-helper","match":{"argv_prefix":["gh","pr","merge"]},"action":"require_preferred","message":"Raw `gh pr merge` bypasses the helper's merge defaults, branch cleanup, and token handling. Use the GitHub helper-backed merge path.","preferred":[{"kind":"script","path":"scripts/gh-pr.py","example_argv":["scripts/gh-pr.py","merge","<pr>","--method","merge","--delete-branch"],"purpose":"Performs the approved merge through the REST helper with normalized defaults and optional branch cleanup."}]},{"id":"prefer-gh-pr-checks-helper","match":{"argv_prefix":["gh","pr","checks"]},"action":"require_preferred","message":"Raw `gh pr checks` can start ad hoc polling and may use the active local GitHub account. Use the PR helper for point-in-time check state, or `babysit-pr` when the task needs ongoing CI/review follow-through.","preferred":[{"kind":"script","path":"scripts/gh-pr.py","example_argv":["scripts/gh-pr.py","checks","<pr>"],"purpose":"Reads PR check runs and commit statuses through the configured helper path."},{"kind":"skill","name":"babysit-pr","purpose":"Watches an open PR until CI/review/mergeability follow-through reaches a terminal or user-help state."}]},{"id":"prefer-gh-run-rerun-wrapper","match":{"argv_prefix":["gh","run","rerun"]},"action":"require_preferred","message":"Raw `gh run rerun` uses the active local GitHub account. Use `babysit-pr` or the automation-token wrapper so Actions reruns are owned by the configured automation identity.","preferred":[{"kind":"skill","name":"babysit-pr","purpose":"Reruns failed PR jobs through the watcher when retry policy recommends it."},{"kind":"script","path":"scripts/gh-with-env-token","example_argv":["scripts/gh-with-env-token","run","rerun","<run-id>","--failed"],"purpose":"Reruns Actions through the configured automation token and fails closed for writes if bot auth is unavailable."}]},{"id":"prefer-bounded-workflow-run-watch","match":{"argv_prefix":["gh","run","watch"]},"action":"require_preferred","message":"Raw `gh run watch` does not diagnose protected-environment waits and can poll without an operator timeout. Use the exact-run workflow babysitter.","preferred":[{"kind":"script","path":"scripts/github_workflow_babysit.py","example_argv":["uv","run","scripts/github_workflow_babysit.py","watch","--repo","OWNER/REPO","--run-id","<run-id>"],"purpose":"Watches one exact run, diagnoses waiting states immediately, and stops on a bounded timeout."}]},{"id":"prefer-secret-scanning-status-reader","match":{"shell_regex":"(?:\\b(?:gh|gh-with-env-token)\\b[\\s\\S]*\\bapi\\b|\\bgithub_api\\.py\\b[\\s\\S]*\\bcall\\b|\\b(?:curl|wget|http)\\b)[\\s\\S]*\\bsecret-scanning/alerts\\b"},"action":"require_preferred","message":"Raw secret-scanning alert operations can expose sensitive alert payloads and are unsupported here. Use the sanitized automation-only status reader for reads.","preferred":[{"kind":"script","path":"scripts/github_read.py","example_argv":["uv","run","scripts/github_read.py","--repo","OWNER/REPO","secret-scanning-status"],"purpose":"Forces hidden-secret REST reads and emits only status, counts, actor evidence, and degraded diagnostics."}]},{"id":"prefer-gh-api-wrapper","match":{"shell_regex":"\\bgh\\s+api\\s+(?!graphql\\b)"},"action":"require_preferred","message":"Raw `gh api` uses the active local GitHub account. Route API calls through `scripts/gh-with-env-token`; write-like API calls must be owned by the configured automation identity.","preferred":[{"kind":"script","path":"scripts/gh-with-env-token","example_argv":["scripts/gh-with-env-token","api","repos/OWNER/REPO/actions/runs","--method","GET","-f","per_page=100"],"purpose":"Runs GitHub API calls through configured automation auth and changes actor only when active-auth fallback is explicitly approved."}]},{"id":"prefer-gh-issue-create-helper","match":{"argv_prefix":["gh","issue","create"]},"action":"require_preferred","message":"Raw `gh issue create` uses active local auth and is fragile for multiline Markdown. Use `github/scripts/gh-issue` for REST-backed title, body, label, assignee, and milestone creation. For project, template, type, relationship, editor, recover, or web-only flags outside that REST subset, use `github/scripts/gh-with-env-token issue create --body-file ...` deliberately.","preferred":[{"kind":"script","path":"scripts/gh-issue","example_argv":["github/scripts/gh-issue","create","<title>","--repo","OWNER/REPO"],"purpose":"Creates issues by reading Markdown from stdin; use `< body.md` or a quoted heredoc for the body."},{"kind":"script","path":"scripts/gh-with-env-token","example_argv":["github/scripts/gh-with-env-token","issue","create","--title","<title>","--body-file","<body-file>","--project","<project>"],"purpose":"Preserves configured automation auth for create flags that are intentionally outside the REST helper's supported subset."}]},{"id":"prefer-gh-issue-comment-helper","match":{"argv_prefix":["gh","issue","comment"]},"action":"require_preferred","message":"Raw `gh issue comment` uses the active local GitHub account and is fragile for multiline Markdown. Use the safe comment helper.","preferred":[{"kind":"script","path":"scripts/gh-comment","example_argv":["scripts/gh-comment","issue","<issue>"],"purpose":"Reads comment Markdown from stdin and posts through the configured automation token."}]},{"id":"prefer-gh-issue-edit-helper","match":{"argv_prefix":["gh","issue","edit"]},"action":"require_preferred","message":"Raw `gh issue edit` uses active local auth and can mangle multiline issue bodies. Use `github/scripts/gh-issue` for REST-backed title, body, label, assignee, and milestone edits. For project, type, parent, sub-issue, or dependency flags outside that REST subset, use `github/scripts/gh-with-env-token issue edit --body-file ...` deliberately.","preferred":[{"kind":"script","path":"scripts/gh-issue","example_argv":["github/scripts/gh-issue","edit","<issue>","--repo","OWNER/REPO"],"purpose":"Edits issues by reading replacement Markdown from stdin; use `< body.md` or a quoted heredoc for the body."},{"kind":"script","path":"scripts/gh-with-env-token","example_argv":["github/scripts/gh-with-env-token","issue","edit","<issue>","--add-project","<project>"],"purpose":"Preserves configured automation auth for edit flags that are intentionally outside the REST helper's supported subset."}]},{"id":"prefer-gh-issue-close-helper","match":{"argv_prefix":["gh","issue","close"]},"action":"require_preferred","message":"Raw `gh issue close` can mangle close comments. For ordinary non-plan issues, run `github/scripts/gh-issue close 123 --repo OWNER/REPO --reason completed < comment.md` or use a quoted heredoc so the close comment is read safely from stdin. If the target is a completed durable plan issue, switch to `github-plan` and use `uv run $CODE_HOME/skills/github/scripts/gh-plan.py close 123 --comment-file comment.md` so planning labels and Project focus stay in sync.","preferred":[{"kind":"script","path":"scripts/gh-issue","example_argv":["github/scripts/gh-issue","close","<issue>","--repo","OWNER/REPO","--reason","completed"],"purpose":"Closes ordinary non-plan issues by reading an optional close comment from stdin; use `< comment.md` or a quoted heredoc for the comment."}]},{"id":"prefer-gh-issue-reopen-helper","match":{"argv_prefix":["gh","issue","reopen"]},"action":"require_preferred","message":"Raw `gh issue reopen` uses active local auth and cannot preserve multiline reopen comments safely. Use `github/scripts/gh-issue reopen 123 --repo OWNER/REPO < comment.md` or a quoted heredoc.","preferred":[{"kind":"script","path":"scripts/gh-issue","example_argv":["github/scripts/gh-issue","reopen","<issue>","--repo","OWNER/REPO"],"purpose":"Reopens issues through REST and reads an optional reopen comment from stdin."}]},{"id":"prefer-gh-release-wrapper","match":{"argv_prefix":["gh","release"]},"action":"require_preferred","message":"Raw `gh release` may create or mutate GitHub state as the active local account. Use the automation-token wrapper for release reads and writes.","preferred":[{"kind":"script","path":"scripts/gh-with-env-token","example_argv":["scripts/gh-with-env-token","release","view","<tag>"],"purpose":"Routes release operations through configured automation auth; release writes fail closed if bot auth is unavailable."}]},{"id":"prefer-gh-workflow-wrapper","match":{"argv_prefix":["gh","workflow"]},"action":"require_preferred","message":"Raw `gh workflow` may dispatch or mutate workflows as the active local account. Use the exact-run babysitter for dispatch and the automation-token wrapper for other operations.","preferred":[{"kind":"script","path":"scripts/github_workflow_babysit.py","example_argv":["uv","run","scripts/github_workflow_babysit.py","dispatch","--repo","OWNER/REPO","--workflow","<workflow>","--ref","<ref>"],"purpose":"Dispatches with automation auth, treats GitHub's returned run id as authoritative, diagnoses waiting runs within one poll, and stops on a bounded timeout."},{"kind":"script","path":"scripts/gh-with-env-token","example_argv":["scripts/gh-with-env-token","workflow","view","<workflow>"],"purpose":"Routes non-dispatch workflow operations through configured automation auth; writes fail closed if bot auth is unavailable."}]},{"id":"prefer-bot-commit-helper","match":{"argv_prefix":["git","commit"]},"action":"require_preferred","message":"Raw `git commit` uses the local human Git identity. Use the bot commit helper so agent-authored commits are owned by the configured automation identity.","preferred":[{"kind":"script","path":"scripts/git-commit-as-bot","example_argv":["scripts/git-commit-as-bot","-m","fix: describe change"],"purpose":"Commits with the configured automation identity as author and committer while preserving normal git commit flags."}]},{"id":"prefer-bot-push-helper","match":{"argv_prefix":["git","push"]},"action":"require_preferred","message":"Raw `git push` uses the local human Git credential or SSH key. Use the bot push helper so push events and resulting Actions runs are owned by the configured automation identity.","preferred":[{"kind":"script","path":"scripts/git-push-as-bot","example_argv":["scripts/git-push-as-bot","-u","origin","task-branch"],"purpose":"Pushes to GitHub using the configured automation token while restoring the normal remote URL afterward."}]}]} |
