Git & GitHub Flow Lifecycle Protocol
This skill governs the complete software delivery lifecycle whenever repository files are created, modified, committed, or delivered via Pull Request—from initial task intake through a fully verified, green Pull Request ready for human review and merge.
Scope Boundary: If the request involves non-code GitHub operations (repository creation/settings,
Panoptic-HuginnEnterprise orjamielapointeruleset authoring, custom properties, backlog/sub-issue/Projects v2 planning, Dependabot/CodeQL/Secret Scanning triage, releases, or cross-repo searches) without modifying local repository files, activate/github-opsinstead.
Related Skills
/github-ops: Non-code GitHub & GitHub Enterprise Cloud (Panoptic-Huginn) repository, ruleset, backlog, Projects v2, security alert, and release administration./ada-spark-pro: Formally verified SPARK Ada 2022 (GNAT 16.1+,gnatprove 16.1+,alr 2.1+) safety-critical robotics kernels and Silver/Gold deductive proofs./python-pro: Python 3.15 (3.14 floor) (uvandpixi),ruff,basedpyright/ty,prek,pytest9+,deptry,pip-audit, andrumdlstandards./rust-pro: Safety-critical Rust 1.99.1+ (pixi,clippy,cargo fmt, Google Rust Styleguide) systems software./cmake-pro: Modern CMake 4.5+ (CMakePresets.jsonv13,cmake --workflow --preset,gersemi) standards./c-pro: Modern ISO C23 (-std=c23,clang-tidy,clang-format, CERT C / MISRA C, sanitizers) systems and robotics safety standards./cpp-pro: Modern C++23 (clang-tidy,clang-format, Google Test, Google Benchmark, sanitizers) standards./jupyter-pro: Interactive Jupyter Notebook and Google Colab workflows and clean-output hygiene./marimo-pro: Reactive marimo Python notebooks,mo.uiwidgets, DAG execution, andpixi/uvtoolchains./marimo-pair: Live marimo kernel driving and durable notebook commits viamarimo._code_mode.
1. High-Thinking Pre-Execution Directives
During your internal reasoning pass before every tool invocation, verify the following state invariants:
- Branch Isolation Check: Confirm the active local Git branch is NEVER
main,master, or a detachedHEADbefore modifying, staging, or committing files. - Docker-Free Native MCP Primary / Keyring Auth / Local-Git Boundary:
- Use
github-mcp-server(plugin-namespaced as lazy-loadedmimir-agent-kit_githubviacall_mcp_tool, or registered globally asgithub) as the primary interface for all remote GitHub operations. mimir-agent-kit_githubruns natively without Docker viascripts/github_mcp_launcher.py(caching the official SHA-256-verifiedv2.1.0static binary in${PLUGIN_DATA}on Ubuntu Linux and macOS) and readsgh auth token --hostname github.comfrom the OS keyring (libsecreton Ubuntu, Login Keychain on macOS). One keyring login spans both personal accounts (jamielapointe) and GitHub Enterprise Cloud organizations (Panoptic-Huginn) with zero PATs on disk.- Partner & Cloud-Sandbox CLI (
ghCLI): UseghCLI (--body-file -single-quoted heredocs) for GraphQL/REST endpoints not modeled by MCP, for the two org/notification tools excluded to fit Antigravity's 64-character tool-identifier limit, or inside Cloud Remote Agents where local stdio servers do not run (see references/gh-cli-fallback.md). Ifgh auth statusreports logged out, halt and ask the user to rungh auth login --hostname github.com. - Use local workspace file tools and local
gitCLI for all file edits, staging (git add), committing (git commit), and pushing (git push). NEVER use remote file-mutation tools (create_or_update_file,push_files,delete_file), as they bypass.pre-commit-config.yamlhooks and local CI gates.
- Use
- Verification-Before-Commit: Never execute
git commit(and never pass--no-verifyor-n) until the full local CI suite—matching all applicable local tooling and.github/workflows/*.ymlPR checks—has executed on the current working tree and exited with code0. - No Autonomous Merge: Unless the user explicitly asks you to merge the Pull Request, your authority terminates once the Pull Request is open, all review threads are resolved, and all remote GitHub CI checks report
SUCCESS(conclusion == "success"). Autonomous merging tomainis strictly forbidden.
2. Tool Boundary Matrix (github-mcp-server vs. gh Partner & Local CLI)
| Operation | Primary (mimir-agent-kit_github) |
Permitted gh Partner / Cloud Fallback |
Forbidden | Reason |
|---|---|---|---|---|
| User Context & Rulesets | get_me; repository_ruleset_read (level: "repository", method: "get_rules_for_branch", branch: "main" — []/404 = unprotected) |
gh api "repos/<o>/<r>/rules/branches/main", gh ruleset check main -R <o>/<r> |
Guessing rulesets; level: "organization" without admin:org scope |
Identifies linear history, squash rules, and required checks across personal & GHEC org repos |
| Issues & Labels | search_issues, list_issues (perPage: 10); issue_read; issue_write; sub_issue_write; list_label; list_issue_types (owner+repo) |
gh issue list/view/create -R <o>/<r> --body-file - |
Inline --body on LaTeX/code; working without an issue |
Preserves structured metadata and deterministic issue tracking |
| Branch Creation | Local git checkout -b "<branch>" && git push -u origin HEAD or create_branch + git fetch + checkout |
gh issue develop <N> -R <o>/<r> --checkout --name "<branch>" |
Committing on main, master, or detached HEAD |
Keeps local working tree and remote tracking ref aligned |
| Edits & Commits | Local file tools (edit_file, write_file) + git add & git commit |
None | push_files, create_or_update_file, delete_file, git commit --no-verify |
Remote API file writes bypass local pre-commit hooks and tests |
| Pushing Commits | git push -u origin HEAD / git push origin HEAD (--force-with-lease origin HEAD only on rebased feature branch) |
None | push_files, git push --force, force-pushing shared branches |
Keeps linear history safely without overwriting shared refs |
| PR Creation & Sync | list_pull_requests (head: "<owner>:<branch>", omit body), create_pull_request (head: "<branch>"), update_pull_request |
gh pr create -R <o>/<r> --body-file -, gh pr edit, gh pr update-branch --rebase |
update_pull_request_branch on required_linear_history; pushing/merging to main |
Enforces squash/linear-history rules and Closes #<N> linkage |
| PR Reviews & Threads | pull_request_read (get_reviews, get_review_comments, get_comments); add_reply_to_pull_request_comment; pull_request_review_write (resolve_thread with owner, repo, pullNumber, threadId) |
gh api graphql (resolveReviewThread, see references/gh-cli-fallback.md) |
Leaving threads open under required_review_thread_resolution |
Satisfies review-thread merge gates (gh pr view --comments cannot resolve) |
| Remote CI & Logs | pull_request_read (get_check_runs, get_status), actions_list, actions_get, get_job_logs (failed_only: true, return_content: true) |
gh pr checks, gh run list -R <o>/<r>, gh run view <id> --log-failed (no --watch) |
Handing off before HEAD_SHA checks reach completed |
Enables deterministic autonomous remote CI self-healing |
| Merge PR | HUMAN DEFAULT (merge_pull_request only on explicit user request) |
gh pr merge --squash (only on explicit user request) |
Autonomous merge_pull_request / gh pr merge, git merge into main |
Autonomous PR merging is forbidden; merge only when explicitly requested after green CI |
3. Entry-State Decision Tree
Evaluate local workspace and remote GitHub state before modifying any repository files (consult references/mcp-tool-reference.md for v2.1.0 parameter details):
- Workspace is on
mainormasterwith uncommitted edits:- Stash local changes immediately:
git stash push -u -m "wip: pre-branching stash". - Execute Stage 1 (Issue Resolution) and Stage 2 (Remote-Linked Branch Creation).
- Apply the stash onto the new feature branch (
git stash pop), then proceed to Stage 3.
- Stash local changes immediately:
- User provided an existing GitHub Issue number (
#<ISSUE_NUMBER>):- Call
issue_read(method: "get"andmethod: "get_comments") to extract requirements and acceptance criteria. - Skip issue creation in Stage 1 and proceed directly to Stage 2.
- Call
- Workspace is already on a feature branch with an open PR that has failing CI or review comments:
- Call
list_pull_requests(head: "<head-owner>:<branch>",fields: ["number","title","state","html_url","mergeable_state"]) andpull_request_read(method: "get","get_check_runs","get_review_comments"). - Jump directly to Stage 5 (Autonomous Remote CI Monitoring & Self-Healing Loop).
- Call
- Standard New Task (Clean workspace on
main, no existing issue specified):- Execute Stages 1 through 6 sequentially without skipping any stage.
4. Six-Stage Execution State Machine
Stage 1: Repository Context & Issue Resolution (github-mcp-server)
- Inspect User Context, Owner Identity & Branch Rulesets:
- Parse repository
ownerandrepofromgit remote get-url origin(handles bothgit@github.com:<owner>/<repo>.gitandhttps://github.com/<owner>/<repo>.git). - Call
get_meto identify the actinglogin(jamielapointe). Critical Dual-Owner Rule: For organization repositories (e.g.,Panoptic-Huginn/*), keepowner: "<org>"on all repo/issue/PR/Actions calls and passget_me.loginonly toassigneesor fork prefixes. - Call
repository_ruleset_read(level: "repository",method: "get_rules_for_branch",owner,repo,branch: "main"). DefaultghOAuth scopes (repo,read:org) evaluate inherited rulesets here across both personal and GHEC org repos (whereaslevel: "organization"requiresadmin:org); treat[]or404on personal repos as unprotected. Checkrequired_linear_history,allowed_merge_methods,required_review_thread_resolution, and required status check contexts.
- Parse repository
- Search for Existing Open Issues:
- Query
search_issues(query: "repo:<owner>/<repo> is:issue is:open <keywords>",perPage: 10) orlist_issues(state: "OPEN",perPage: 10) to avoid duplicate issues.
- Query
- Create Issue (If None Exists):
- Call
list_label(owner,repo) and optionallylist_issue_types(owner,repo); omittypeunlesslist_issue_typesreturns enabled entries. - Call
issue_write(method: "create") with:title:<type>(<scope>): <concise summary>(e.g.,feat(estimators): ...,fix(ci): ...,refactor(core): ...,perf(kernels): ...,test(unit): ...,docs(thesis): ...,chore(deps): ...)body: Structured Markdown containing Problem Statement, Technical Scope, and Verifiable Acceptance Criteria.labels: Applicable labels fromlist_label(e.g.,["enhancement"],["bug"],["documentation"]).assignees:[<login from get_me>]if appropriate.
- Call
- Record the resulting
<ISSUE_NUMBER>for all subsequent branch, commit, and PR operations.
Stage 2: Remote-Linked Branch Creation
Synchronize Local Default Branch:
git checkout main git pull --ff-only origin mainCreate and Push Feature Branch:
Format branch name as
<type>/<ISSUE_NUMBER>-<short-kebab-slug>(e.g.,feat/131-rotational-factor-graph,fix/142-pit-calibration-bound).Option A (Local Git + Remote Tracking — Preferred):
git checkout -b "<type>/<ISSUE_NUMBER>-<short-kebab-slug>" git push -u origin HEADOption B (Remote Creation via
github-mcp-servercreate_branch+ Local Checkout): Callcreate_branch(branch: "<type>/<ISSUE_NUMBER>-<short-kebab-slug>",from_branch: "main"), then run:git fetch origin git checkout -b "<type>/<ISSUE_NUMBER>-<short-kebab-slug>" "origin/<type>/<ISSUE_NUMBER>-<short-kebab-slug>"Option C (Optional
gh issue developLink):gh issue develop <ISSUE_NUMBER> -R "<owner>/<repo>" --checkout --name "<type>/<ISSUE_NUMBER>-<short-kebab-slug>"may also be used. IncludingCloses #<ISSUE_NUMBER>in the Stage 4 PR body automatically links the PR and branch to the issue even withoutgh issue develop.
Verify Branch Isolation Invariant:
git branch --show-currentAbort immediately if the output is
main,master, or empty.
Stage 3: Implementation & Mandatory Pre-Commit Local CI Gate
Implement Scoped Changes & Tests:
- Implement the feature, bugfix, or refactor adhering to workspace rules (
AGENTS.md) and language skills (/python-pro,/rust-pro,/cmake-pro,/c-pro,/cpp-pro,/ada-spark-pro,/marimo-pro). - Add or update unit/integration tests covering the new behavior or bugfix.
- Implement the feature, bugfix, or refactor adhering to workspace rules (
Inspect
.github/workflows/*.ymlfor PR Job Parity:- Check all workflows in
.github/workflows/triggered bypull_request(e.g.,ci.yml) so you know every check that remote GitHub Actions will execute.
- Check all workflows in
Detect and Execute the Full Local CI Pipeline BEFORE
git commit: Inspect.github/workflows/*.ymland the repository root, then run all applicable checks until every step exits with code0cleanly (without further formatter edits). Quick reference (full ecosystem table in references/local-ci-matrix.md):- Antigravity Plugin (
scripts/ci/run_local_ci.sh):./scripts/ci/run_local_ci.sh(plusuv run rumdl check --no-exclude skills/<changed-skill>when editingskills/) - Pixi / Python / Cross-Ecosystem (
pixi.lock):pixi run prek run --all-files --show-diff-on-failure(orpre-commit),pixi run ruff check&ruff format --check,pixi run basedpyright&ty check,pixi run pytest,pixi run build(if defined) - Pure
uvPython (uv.lock):uv run prek run --all-files,uv run ruff check .&ruff format --check .,uv run basedpyright&uv run ty check,uv run deptry .,uv run pip-audit,uv run pytest - C/C++23 (
CMakePresets.json), Rust (Cargo.toml), SPARK Ada (alire.toml), Node, Go, Docs: Run configured format/lint/proof/test workflows per references/local-ci-matrix.md.
- Antigravity Plugin (
Stage 4: Atomic Commit, Push & Pull Request Creation
Workspace, DVC & Secret Hygiene Audit:
- Run
git statusandgit diffto verify:- Zero untracked scratch scripts, temporary files, build artifacts (
dist/,build/), or secrets (.env,.dvc/config.local) are staged. - In DVC-enabled repositories (
heimdall-astro), raw data directories (data/latest/,data/baseline/*.zarr,*.html) are never staged in Git; ifdata/baseline.dvcwas updated, confirmpixi run dvc pushcompleted first.
- Zero untracked scratch scripts, temporary files, build artifacts (
- Run
Stage and Commit Verified Changes (Never Use
--no-verify):git add <specific-modified-files> git commit -m "<type>(<scope>): <concise summary> (#<ISSUE_NUMBER>)"Keep the subject line under 72 characters and include a structured multi-bullet body explaining the what and why so squash-merges preserve full architectural context.
Push Branch to Remote:
git push -u origin HEADCreate or Update Pull Request via
github-mcp-server:- Check if a PR template exists (
.github/pull_request_template.mdor.github/PULL_REQUEST_TEMPLATE/). - Call
list_pull_requests(owner,repo,head: "<head-owner>:<branch-name>",state: "open",fields: ["number","title","state","html_url","head"]). - If no open PR exists, call
create_pull_request(orupdate_pull_requestif one already exists):owner/repo: Fromgit remote get-url origin(e.g.,Panoptic-Huginnorjamielapointe).title:<type>(<scope>): <concise summary> (#<ISSUE_NUMBER>)head:<branch-name>(same-repo branch;"<fork-owner>:<branch-name>"only for cross-fork PRs)base:maindraft:false(unless the user explicitly requested a draft PR)body:## Summary Closes #<ISSUE_NUMBER> - **Root Cause / Motivation:** <concise explanation> - **Key Changes:** - <bulleted summary of architectural and code changes> --- ## Verification & Local CI - [x] Pre-commit & Hygiene (`<exact command>`): Passed - [x] Static Analysis / Type Checking (`<exact command>`): Passed - [x] Test Suite (`<exact command>`): `<N> passed[, <M> skipped]`Note: Only list checks actually executed on the current working tree.
- Check if a PR template exists (
Stage 5: Autonomous Remote CI Monitoring, Review Thread Resolution & Self-Healing Loop
Never hand off a Pull Request immediately after creation or push. Wait for all remote GitHub Actions workflows and check runs on the pushed HEAD commit SHA to complete and self-heal any failures.
Wait & Poll Remote Check Runs (
github-mcp-serverPrimary):- Capture
HEAD_SHA=$(git rev-parse HEAD). - Use the
scheduletool for a ~20–30 second timer if waiting between polls (avoid blocking shellsleeploops), then poll usinggithub-mcp-server:- Call
pull_request_read(method: "get_check_runs",owner,repo,pullNumber: <PR_NUMBER>). - Call
actions_list(method: "list_workflow_runs",owner,repo,workflow_runs_filter: {"branch": "<branch-name>"}).
- Call
- Continue polling until all check runs matching
HEAD_SHAhavestatus == "completed".
- Capture
Check Review Threads & Base Branch Currency:
- Call
pull_request_read(method: "get_review_comments",owner,repo,pullNumber: <PR_NUMBER>— paginate withaftercursor ifhasNextPageis true) andpull_request_read(method: "get",owner,repo,pullNumber: <PR_NUMBER>). - If any actionable review comments exist, address them locally, verify Stage 3 + push, reply via
add_reply_to_pull_request_comment, and resolve each thread viapull_request_review_write(method: "resolve_thread", passingowner,repo,pullNumber, ANDthreadId: "<PRRT_node_id>"— required by JSON schema). - If the PR is behind
main:- When
required_linear_historyis active (default acrossPanoptic-Huginnandjamielapointerulesets), do NOT callupdate_pull_request_branch(it creates a merge commit). Rungit fetch origin main && git rebase origin/main, re-run Stage 3, and push withgit push --force-with-lease origin HEAD. - Only call
update_pull_request_branchwhen linear history is not enforced and merge commits are permitted.
- When
- Call
Evaluate Remote CI Outcome:
- All check runs & workflow runs report
status == "completed"andconclusion == "success"(or"skipped"/"neutral"with0failures): Proceed to Stage 6. - Any check run or workflow run reports
conclusion == "failure"/"cancelled"/"timed_out"/"action_required": Enter the Remote CI Remediation Loop below.
- All check runs & workflow runs report
Remote CI Remediation Loop (Max 5 Iterations):
- Step 5a — Extract Failure Logs: Identify failing
run_idviaactions_list(list_workflow_runs, thenlist_workflow_jobswithresource_id: "<run_id>"), then callget_job_logs({"owner": "<owner>", "repo": "<repo>", "run_id": <FAILED_RUN_ID>, "failed_only": true, "return_content": true, "tail_lines": 500}). Fallback:gh run view <FAILED_RUN_ID> -R "<owner>/<repo>" --log-failed. - Step 5b — Root-Cause Diagnosis: Isolate code/test/typing/formatter differences, missing lockfile deps, OS/runner drift, workflow misconfiguration, or external GitHub/secret outages.
- Step 5c — Local Fix & Stage 3 Re-Verification: Fix locally and re-run Stage 3. Never push speculative CI fixes without local verification.
- Step 5d — Commit, Push & Re-Poll: Commit (
fix(ci): resolve remote <job-name> failure (#<ISSUE_NUMBER>)),git push origin HEAD, and return to Step 5.1 on the newHEAD_SHA. - Circuit Breaker (Max 5 Iterations): Halt and report failure logs, root cause, and attempted fixes to the user if remote CI still fails after 5 iterations or hits an unrecoverable permissions/infrastructure outage.
- Step 5a — Extract Failure Logs: Identify failing
Stage 6: Antigravity Walkthrough & Human Merge Handoff
Once local and remote CI pass (0 failures) and all review threads are resolved:
- Verify
git statusis clean andgit rev-parse HEADmatchesgit rev-parse origin/<branch-name>. - Do NOT autonomously merge the Pull Request (call
merge_pull_requestorgh pr mergeonly if the user explicitly asked you to merge it) and do NOT delete the branch during handoff. - Present a concise completion summary (updating
walkthrough.mdif in/planmode) with: Linked Issue (#<ISSUE_NUMBER>URL), Remote Branch +<HEAD_SHA>, Pull Request (#<PR_NUMBER>URL), Local CI Summary (exact commands + pass/skip counts), Remote CI Summary (SUCCESSper job), and Merge Readiness confirmation (rulesets satisfied, ready for human Squash Merge).
References
- references/mcp-tool-reference.md:
mimir-agent-kit_github(v2.1.0native binary) schemas, dual-owner routing, JSON schema quirks, excluded tools. - references/gh-cli-fallback.md: Keyring
ghauth & scope diagnostics,--body-file -LaTeX/Markdown safety, GraphQLresolveReviewThread, and Cloud Remote Agentghrecipes. - references/local-ci-matrix.md: Full multi-ecosystem Stage 3 pre-commit CI detection and command matrix.