github-loop-engineering-skill skill

GitHub Loop Engineering

Use GitHub Issues and Projects as the durable control plane and memory for Loop Engineering. Move each work item through one bounded, evidence-gated pass, using only the GitHub MCP tools the host exposes.

Four ideas carry the skill:

• The issue is the unit of handoff. Every issue stays cold-startable: someone with no prior context, including a fresh agent session, can read it and act on it without asking anyone or reading chat history.
• A parent issue is the unit of parallel work. Its sub-issues and the blocked-by dependencies between them form a work graph. Any agent can take the parent, find the children that can start now, and run them in parallel, each starting cold from its own issue.
• Evidence is recorded once and reused. Each check, review, and decision is written to the issue or the pull request together with the commit it covers. Whoever comes next reads that record and repeats only what it doesn't cover.
• Code is reviewed locally, pull requests for their content. Each commit and each high-risk change is reviewed locally, under the team's AI controls, before the pull request opens. Reviewing a pull request never means reviewing its code: it checks only that the pull request's content meets what this skill requires.
• Agents merge what evidence can settle. An agent merges a pull request that passes the merge gate. A human confirms what evidence can't settle, above all how an interface looks and feels.

Contents

• Read the references
• Rules
• The loop
• Verify once
• Work-item rules
• Operations
• Failure handling

Read the references

Reference	Read it
references/github-mcp-tools.md	Before the first GitHub MCP operation in a session, and whenever a capability or payload is unclear
references/work-item-format.md	Before creating an issue or substantially rewriting an issue body. It defines the cold-start contract and check
references/pull-requests.md	Before opening, classifying, reviewing, or merging a pull request
references/fan-out.md	Before handing leaves to parallel agents, and when you resume a fan-out after an interruption
references/initialization.md	When a repository's issues or board are used for the first time
references/issue-templates.md	When installing issue templates, or when a repository's templates differ from this skill's in assets/issue-templates/

Rules

1. MCP only. Use only the connected GitHub MCP server for GitHub reads and writes. Do not fall back to gh, curl, direct REST, or handwritten GraphQL. The only exceptions are the operations under Capability gaps, each after the user explicitly authorizes it.
2. The live schema wins. Treat the connected tool schemas as authoritative. MCP hosts may namespace tool names, so match the terminal tool name and its semantics rather than assuming a prefix.
3. Discover at runtime. Find the repository, project, fields, options, labels, issue types, and item identifiers in the current session. Never copy IDs or option values from another repository, and never cache them in this skill.
4. One transition at a time. Frame one authorized state transition, with its evidence and its stop condition, and make the smallest mutation that completes it.
5. A write's response is a claim. Re-read the affected resource after each write. The transition is verified only when a fresh read shows the intended state.
6. Persist for a cold start. Write verified state, decisions, and remaining work to GitHub so that another agent or a human can resume without you. An issue that fails the cold-start check is not finished being written.
7. Verify once. Record each check with the commit it covers, and reuse a recorded check instead of running it again, as described in Verify once.
8. Preserve what exists. Keep repository conventions and existing content unless the user explicitly asks to change them. Repository guidance wins over every default in this skill.
9. Brief delegated agents. A delegated agent doesn't inherit this skill. Put the rules in its prompt: GitHub access through MCP only, the exact tools and inputs, which writes it may make itself, never writing content it hasn't read, and when to stop and report. Also give it the tool notes it needs, such as reading a pull request's labels with pull_request_read.
10. Never merge on your own judgment. Merge a review:ai pull request only when it passes the merge gate on its current head commit. Merge a review:human pull request only after a human approved its current head commit for merging and the gate's other conditions hold, as described in Human review.
11. Public means published. In a public repository, every issue, comment, pull request, commit, and CI log is published the moment it is written, and edit history keeps what a later edit removes. Never write secrets, internal hostnames or addresses, customer names, or personal data there. Read what a delegated agent prepared before it goes out.

The loop

Run every operation as:

Discover → Frame → Act → Verify → Persist → Continue or stop

• Discover: rebuild the current state from GitHub, not from memory.
• Frame: select one bounded transition, its authorization, and the proof of success.
• Act: perform the minimum mutation in dependency order.
• Verify: compare freshly read state with the intended state.
• Persist: write durable evidence, decisions, blockers, and handoff context.
• Continue or stop: route the next authorized step, or stop at done, ambiguity, missing evidence, missing capability, repeated failure, or a human gate.

Do not collapse Act and Verify into one step. A successful write response proves only that GitHub accepted a request, not that automations, linked state, or concurrent edits produced the intended result.

Discover

Identify the target:

• the repository owner and name;
• the project owner, owner type, and project number;
• the issue, pull request, or project item being changed;
• the requested final state.

Take these from an explicit URL or the repository context when possible. If several repositories or projects remain plausible and a write could land in the wrong place, ask one concise question before mutating anything. Do not guess a project merely because its title resembles the repository name.

Inspect the available GitHub MCP tools and their schemas. Board management normally needs:

• issues for issue reads, writes, comments, types, and sub-issues;
• projects for project discovery, item attachment, and field updates;
• labels when repository labels must be listed or created;
• context, repos, and pull_requests when identity, repository guidance, or pull requests are involved;
• actions when CI must be read and the token can't read check runs.

The official server's default toolsets omit projects, labels, and actions. If a required write tool is absent, the server is read-only, or authorization is insufficient, stop before the mutation and report the missing toolset or permission. Do not bypass the boundary with another API client.

If no GitHub MCP server is connected, follow Bootstrap when the server is absent: connect only the official github/github-mcp-server, get the host's approval before downloading software, changing configuration, or starting authentication, and keep credentials in the host's secret store, never in the repository, the skill, a command transcript, or chat. Then resume from a fresh Discover pass. If the environment can't install or connect MCP servers, stop with the exact step the user must complete.

Before the first write:

1. Read repository guidance and issue templates when available. When guidance says the templates come from this skill, compare them as described in Keep issue templates current.
2. List matching projects and verify the selected project's title and number.
3. List the project's fields and their current options.
4. List the existing repository labels.
5. List issue types and custom issue fields only when the repository supports them or the request needs them.
6. When updating existing work, read the current issue, its labels, relevant comments, hierarchy, and project item.

Paginate until uniqueness is established. Prefer human-readable field and option names when the current schema resolves them by name.

First-use gate. If this Discover pass shows that the repository's issues, its board, or its pull request review have never been set up for this workflow, as defined in references/initialization.md, stop the original transition. Propose initialization, and run it only after the user authorizes it. Resume the original request from a fresh Discover pass once initialization is verified or explicitly declined. If the user declines, work with the vocabulary that exists and don't invent labels or statuses.

Frame

Define:

• the current observed state;
• one requested or policy-authorized next state;
• the exact issue and Project mutations needed;
• the evidence that will prove success;
• the conditions that require stopping or human input.

When repository guidance sets no policy, use these defaults:

• Represent actionable work as a real issue, not a draft project card.
• Use the repository's established language and terminology.
• Write the issue body to the cold-start contract in the work-item format: why, what, current state, acceptance criteria, and pointers, with absolute dates and no session-only references.
• Use project fields as the source of truth for board state.
• Triage by best judgment, as described under Status and Priority.
• Add a duplicate priority label only when the repository already requires field-and-label synchronization.
• Reuse existing labels. Create or rename labels only when the user requests it, standing repository policy clearly authorizes it, or an authorized initialization adds them.
• Leave assignees empty on creation unless the user names someone. Assign the authenticated user when work starts, as the claim on the issue.
• Use issue types only when supported. Do not emulate them with new labels unless repository policy says to.
• Treat follow-up work an agent discovers as a proposal. Create it only when the user requested discovery-and-creation or the repository has a standing intake policy. Give a follow-up you create the milestone or parent it belongs to, and don't add it to the current run unless it belongs there. A finished leaf often turns up one or two follow-ups, and a run that takes on all of them doesn't finish.

Act

Perform related mutations in dependency order. Change only the fields, labels, body sections, relationships, or state the framed transition requires. Keep mutations idempotent when the API supports stable issue locators or read-before-write merging.

Verify

Re-read the affected issue, hierarchy, pull request, or project item after each mutation, and request every field you need to compare. Verify both sides when one operation can trigger an automation elsewhere, such as closing an issue and moving a Project status.

Whenever the transition created an issue, changed its body, or changed its Status, run the cold-start check on the body as read back from GitHub. A failed check means the transition is not yet verified.

If an operation partially succeeds, rebuild the involved state and recover only the missing part. Retry only with new evidence or a changed strategy. Do not repeat an unchanged failing call.

Persist and route

Keep the issue body as the durable current-state snapshot. Put chronological decisions, validation, gotchas, and partial progress in comments. Keep Project fields synchronized with the verified lifecycle state.

Report the final issue URL or number, the Project, the fields changed, the evidence, and the observed result. Route only an authorized next step. Otherwise stop with a precise handoff that describes the state, the blocker, and the condition for the next loop.

Verify once

Work passes through several hands: the agent that implements it, a coordinator, a reviewer's agent, the agent that merges it, and often another person's agent in a later session. Each check runs once. Its result is recorded, and everyone after that reads the record instead of running the check again.

Record. When you run a check, a review, or an audit, write the result where the next reader will look. Anything about a change goes into the pull request's verification record. Acceptance evidence and decisions go into the issue. Each record names the commit SHA it covers, who ran it (the person, or the agent and its model), what it covered, and the result.

Reuse. Before you run a check, a review, or an audit, or delegate one, look for its record. A record is a claim, and you test a claim by reading it against what GitHub and git show: the commit it names is in the pull request, CI ran on that commit, a fix it names exists. You don't test it by doing the work again. Then do only what the record doesn't cover: the commits after the one it names, an area it leaves out, or a check nobody recorded. Add your result to the record, so the next reader doesn't repeat your part either.

A record in any form counts, including one written before this format. One that names no commit covers the commits that existed when it was written.

Don't reuse a record when:

• it was written by someone without write access to the repository, as in a pull request from a fork;
• what you observe contradicts it. Then run that check yourself and correct the record;
• the user, a human reviewer, or repository guidance asks for an independent check at that point.

Nothing else is a reason to repeat recorded work. A high-risk change is not one. Neither is a rule that sends some kind of work to a stronger model or a dedicated agent: such a rule decides who runs a check, not whether a finished check runs again.

Reading your own write back, as rule 5 requires, is not a repeated check. It is one cheap read, and it is how the write gets verified in the first place.

Work-item rules

Status

Map workflow intent to an existing project option. Never assume exact option names:

• unreviewed intake → Triage, Inbox, or equivalent;
• accepted but not started, including work that waits on other issues → Todo, Ready, or equivalent;
• active work → In Progress, Doing, or equivalent;
• work stopped by something outside the work graph → Blocked or equivalent;
• completed work → Done, Complete, or equivalent.

If no unambiguous option exists, leave the field unchanged and ask for the intended mapping.

Agents triage by best judgment: accepted work moves to the accepted option, and rejected work is closed as not planned. Leave triage to humans when repository guidance or the project's own Status descriptions reserve it, as boards initialized with earlier versions of this skill do.

Waiting on another issue is not a blocked status. Record the prerequisite as a native blocked-by dependency and keep the item in the accepted option. GitHub marks the item blocked until every prerequisite closes, so the Project filter -is:blocked separates work that can start now from work that waits. Use the blocked option only for blockers outside the work graph, such as a pending decision, missing hardware or access, or another team.

A parent issue moves to the active option when its first child starts, and it closes through its own completion ritual once every child is closed.

Project automations can change state on their own, so check the documented workflows before acting:

• An Auto-close issue workflow closes the issue as soon as Status becomes the completed option. Never set the completed option before the completion ritual. Close the issue and let the automation move Status, then verify.
• When an issue is reopened and no reopen workflow is documented as enabled, move Status back to the correct option explicitly.

Priority

Use the project's existing priority scheme. Infer meaning only from documented option names or repository guidance. Do not invent P0, P1, or P2, and do not create a Priority field as part of an ordinary issue update. The baseline scheme in the initialization reference applies only after the user authorizes initialization.

Set Priority when you create an issue, by best judgment against those meanings, unless repository guidance reserves it for humans. When the current focus follows milestones, raise the next milestone's issues when it becomes current.

When the repository mirrors priority in labels, read the full current label set, remove only the superseded priority label, add the new one, and preserve every unrelated label. An organization can also define an issue field named Priority. It is separate from the Project's field, so set it only when repository guidance chose it as the mirror.

Acceptance criteria

Write observable, testable checkbox items. Include commands, user-visible behavior, or concrete artifacts where appropriate. Mark an item complete only when evidence supports it, and record that evidence in an issue comment or in a test report in the repository's docs. Do not close an issue with incomplete criteria unless the user deliberately descopes them and the issue records that decision.

A short answer that skips a criterion, such as "don't test that", can mean "not now", for example because the hardware or access doesn't exist yet, rather than "never". Record the criterion as pending, with the reason and the condition for doing it, unless the user says to drop it. When the answer could mean either, ask in one line.

A claim that something didn't happen, such as a scheduled run that never started, is evidence only once it can no longer happen. Scheduled workflow runs can start hours late.

Dates and notes

Use absolute ISO dates (YYYY-MM-DD) for blockers, decisions, and completion notes. Put durable current-state information in the issue body and chronological implementation notes in comments.

Operations

Create an issue

1. Search for likely duplicates.
2. Read labels, optional issue types, repository templates, and the work-item format.
3. Create the issue with a complete cold-startable body and only known labels, milestone, and type. Add assignees only when the user names them.
4. Add it to the selected project. If the project's auto-add workflow already attached it, treat an already-present response as success.
5. Set the requested project fields one at a time, by current field and option name.
6. Read back both the issue and the project item, including every field just changed, and run the cold-start check on the returned body.

Update or reprioritize an issue

1. Read the issue and its current project item.
2. Update the relevant issue metadata or body. Preserve the rest of the body and every unrelated label.
3. Update only the requested project fields.
4. Verify that the issue and the board agree.

When one authorized transition sets the same field value on several items, such as moving a set of accepted children to the ready option, use the batch project update if the connected schema exposes it. Then verify every item, because a batch can partially succeed.

Start work

Starting work means claiming the issue, moving it to the existing active-status option, updating State in the body, and checking the issue for overbuilding. Add an implementation note only when it provides durable context.

Claim the issue

Nobody is assigned when an issue is created. At the start transition, the assignee is the claim: it tells other people and agents that the issue is taken, so two of them don't pick up the same work. Claim the issue before any other work on it:

1. Read the current assignees.
2. If the authenticated user is already assigned, keep the assignment.
3. If nobody is assigned, assign the authenticated user without asking. Resolve the login with get_me, because MCP assignee lists don't accept @me. Leave the issue unassigned only when the request or repository policy says so, for example when only a human assigns work.
4. If someone else is assigned, don't start, reassign, or add anyone. Report the current assignee and ask how to proceed.
5. Send the complete intended assignee set, then re-read it. If the read-back shows another assignee, someone claimed the issue at the same time: remove only your own login and handle it as in step 4.

Check the issue for overbuilding

An issue can ask for more than its goal needs, and an agent that executes it faithfully builds all of it. Only the user can descope an acceptance criterion, so give them the chance before the work starts. Right after you claim an issue, and before you write any code, compare its What and acceptance criteria with its Why and look for items that:

• don't serve the stated Why;
• build generality for a need nobody has stated, such as an option, plugin point, or abstraction layer with only one user;
• already exist in the repository, fully or in part;
• require verification beyond what the repository's guidance asks for at this stage.

When none match, continue without saying anything. A check that asks every time slows every loop. When some match, ask the user once, with all the items in one question set, as for a pending decision: for each item, name the criterion or scope line, say why it looks unneeded, and give the choices, which are drop it, move it to a follow-up issue, or keep it, with your recommendation first. Keep working on the parts the answer doesn't affect while you wait.

Record the answer in the issue as an explicit descoping decision with its date and reason, in Out of scope and an implementation note, so that someone who resumes the issue cold knows why the criteria are fewer. A moved item becomes a follow-up issue only under the follow-up rule in Frame. In a fan-out, the coordinator runs this check on each leaf before handing it out, and a leaf agent that finds overbuilding during the work reports it rather than descoping on its own.

While you work, build only what the acceptance criteria need. An improvement you notice along the way is a follow-up proposal, not part of the current change.