Skip to content

akunzai/agent-skills / skills/setup-agent-ready-repo

setup-agent-ready-repo

Unverified

Set up a repository so agents can file tickets, open pull or merge requests, and verify their own changes.

assets/templates/pull-request.md

View on GitHub
<!-- Template. Name the file pull-request.md on GitHub, merge-request.md on GitLab. -->
<!-- Replace every <angle placeholder> and every inline `placeholder` span;
     delete lines that do not apply. -->

# <Pull | Merge> requests

Write <PR | MR> titles, descriptions, and comments in **<language>**.
**Git commit messages are English**, imperative, subject under 72
characters — they live in history and get searched by tooling.

<!-- If the repo has a native template, say so and stop duplicating it:
This repo's `<.github/PULL_REQUEST_TEMPLATE.md | .gitlab/merge_request_templates/X.md>`
is authoritative on structure. What follows only adds what it does not say. -->

## Preparing

- Work on a feature branch. Never prepare a request from the default branch.
- <Use a concise descriptive title with no Conventional Commit prefix,
  because one request may carry more than one kind of change. | Prefix the
  title with a Conventional Commit type, matching this repo's merged
  history.> Delete the alternative that does not apply.
- Link the issue in the template's Related Issue section (`Closes #<n>`). If
  there is no tracked issue, drop the section — never leave an unlinked
  `Closes #` or empty issue marker.
- **Do not open a request, draft included, without the developer asking.**
- Open a request with `<gh pr create | glab mr create>` and update it with
  `<gh pr edit | glab mr update>`.

## Description shape

1. A plain-language opening: what changed and why, as a reviewer who did
   not write it would need it.
2. A visual the forge renders inline, chosen by what changed:

   | Change | Visual |
   | --- | --- |
   | Flow or state transition | Mermaid `flowchart` / `stateDiagram` |
   | Cross-service or API interaction | Mermaid `sequenceDiagram` |
   | Data model | Mermaid `erDiagram` |
   | Appearance | Before/after screenshots |
   | Multi-step interaction | Short recording |
   | Backend or library only | None; test output instead |

   Pair before and after. At most one diagram unless it is such a pair.

   In a Mermaid label, write a path parameter as `:id`, not `{id}` — `{}`
   opens a rhombus node and fails the parse — and break lines with `<br/>`,
   not `\n`, which is not a line break inside a quoted label.

   Upload the file with the repeatable `--attach` flag —
   `<gh pr create --attach './after.png#After' | glab mr create --attach ./after.png>`.
   Alt text follows the path after `#`, and a path the body already
   references as `![alt](./after.png)` is rewritten to point at the
   uploaded asset. Only when capture is genuinely impossible, leave a
   named placeholder comment.
3. A collapsed technical trailer holding implementation notes, verification,
   and lessons learned. Skip affected paths — the forge's own diff view
   already shows those.

<!-- Keep the line below even when the visual guidance above is cut
short. It is the one rule whose absence costs someone else. -->
**No personally identifiable information in any attachment**, whatever
you end up attaching. `verification.md`'s capture rules say what that
means here.

## Merge confidence

Add this section only when a plain `git revert` would not undo the change or
an external consumer is affected; otherwise omit it. A known risk is
mergeable when evidence and a mitigation cover it:

- **Risk**: what could go wrong and who notices — which users, consumers, or
  downstream systems — and how soon.
- **Evidence**: the tests, CI jobs, smoke output, or staging check that
  exercise the risky path. Confirm a CI job actually ran on this change; a
  job skipped by a path filter is no evidence.
- **Mitigation**: what limits the damage — a backup and restore path, a
  feature flag, a staged rollout, or written confirmation from whoever runs
  an external dependency.

With neither evidence nor mitigation, say so and keep the request a draft.

## Tests land with the behaviour

- **Product logic**: `placeholder:paths`. A change here lands with its tests in the
  same request.
- **Exempt**: `placeholder:paths` — documentation, CI configuration, scripts, and
  dependency bumps with no behaviour change.
- **Structurally untestable** code — configuration classes, all-static
  factories — is declared in the description, naming what covers it instead.

No coverage threshold. The reviewer judges whether the new behaviour is
actually exercised.

## Review readiness

Nothing unverified enters review. Two orders satisfy that:

- **Default**: verify locally per `verification.md`, then open the
  request with the evidence.
- **When only a deployed environment can verify** — see the list in
  `verification.md` — open the request as a draft
  (`<gh pr create --draft | glab mr create --draft>`), let the pipeline
  deploy, verify against it, attach evidence citing the pipeline or
  deployment id and the commit SHA, then mark it ready.

State in the description which paths were verified and which were not,
with the reason.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall