agentleFS
zajcazajca/pohunek/.agents/skills/contribute/SKILL.md

contribute

Skill9 starsChanged 2 days agoMITView on GitHub

Guide public work on the Pohunek repository from issue selection through eligibility, current reservation limits, implementation, verification, pull-request submission, and handoff. Use when planning or making a repository contribution; not when operating Pohunek sessions.

  • Commits and pushes

16 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use review-pr.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • DockerSkill

    review-pr

    Review one or more incoming Docker documentation pull requests as a maintainer. Independently validate technical claims, assess editorial fit and information architecture, choose a verdict, and draft exact inline or PR-wide feedback behind a confirmation gate. Use for requests such as "review PR 123", "is this PR correct?", "does this information belong here?", "validate this PR", or "help review backlog PRs". Do not use to maintain or fix a PR you own; use maintain-pr for that.

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

9 rules. 0 are common, 6 are distinctive, and 3 are very specific to this project.

  • 0

    Common

    Most of the 15 edited versions we read keep these.

  • 6

    Distinctive

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use the issue body and comments as the scope and decision record.

    line 24
  2. Distinctive:

    Check that the issue has a concrete outcome, stable acceptance criteria, focused verification, resolved dependencies, capability/size cues, …

    line 32
  3. Distinctive:

    If scope or acceptance is unclear, ask in the public issue before investing in implementation.

    line 40
  4. Very specific:

    Create a repository in your own account from the template pohunekd/pohunek-plugin-template and name it pohunek-plugin-<name>.

    line 49
  5. Distinctive:

    If your plugin needs something core does not provide (a new integration handler, descriptor key or hook schema), open a core issue first.

    line 63
  6. Distinctive:

    Use a branch in your authorized fork and keep changes within the issue's criteria.

    line 96
  7. Very specific:

    When a task involves operating Pohunek itself, reuse the shipped Pohunek agent skill for its CLI and safety contract.

    line 104
  8. Very specific:

    Run the issue's focused checks and every applicable repository gate.

    line 109
  9. Distinctive:

    If no review has arrived some hours after green CI, mention the maintainer on the pull request.

    line 153

“Common” is measured: kept by at least 6 in 10 of the 15 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Contribute to Pohunek

Help a human or agent contribute through public issues and pull requests. The accepted permission and custody rules live in .github/agent-workflow.json and the github-workflow skill; follow those sources when this guide is incomplete. An outside contributor needs no private Project access or maintainer credentials. A request to contribute grants no repository, host, credential, model-budget, review, merge, or release authority.

Choose and check work

Find public scope in the open issues and the readiness:ready queue. Use the issue body and comments as the scope and decision record. With the GitHub CLI, inspect an issue and its linked work with:

gh issue view NUMBER --repo zajca/pohunek --comments
gh pr list --repo zajca/pohunek --state open --search "NUMBER in:body"

Check that the issue has a concrete outcome, stable acceptance criteria, focused verification, resolved dependencies, capability/size cues, and a named available review route. Check comments, active assignments, and linked pull requests for current conflicts. readiness:ready is a maintainer-managed eligibility signal, not proof that work is unclaimed, a reservation, or a promise to merge. The public policy and current meanings are in publicContribution.

If scope or acceptance is unclear, ask in the public issue before investing in implementation. If the work is not listed, propose it using the work-item issue form; follow the github-workflow skill for issue handling.

Contribute a plugin

A plugin is not contributed to this repository. To write a runtime package:

  1. Create a repository in your own account from the template pohunekd/pohunek-plugin-template and name it pohunek-plugin-<name>. The pohunekd/plugin-* names and the pohunek. package-id namespace are reserved for official plugins.
  2. Follow Plugin repositories: declare runtime_api, the runtime features you require and a core range, and keep the template's CI, which calls the reusable workflows pinned to a core release tag.
  3. Publish releases from your repository's CI with the template's release workflow; it attests the archive. Owners can install it by digest at once (community tier).
  4. To make it installable by id (verified tier), open a pull request to pohunekd/pohunek-plugin-index that adds your entry. Its CI checks the attestation and runs the kit proof; a named reviewer approves it.
  5. If your plugin needs something core does not provide (a new integration handler, descriptor key or hook schema), open a core issue first. The core change lands behind a runtime feature, and your plugin adopts it against the nightly kit. Do not patch core for one plugin.

The template, the plugin kit, the index and its CI are available from a later release (What is available when). Until then steps 1, 3 and 4 cannot be completed: do not add the plugin here; propose it in a core issue under #1609 and wait.

Understand reservation and custody

The binding rules are in Public contributions and authority and contributionPolicy in .github/agent-workflow.json. In practice:

  • Automatic reservation is unavailable until the coordination service of #805–#811 is delivered. Until then, only a maintainer records a manual reservation in public issue evidence. A request, label, assignee, or unanswered comment is not a grant. Do not invent or imply a claim command.
  • You may propose work, request a reservation, work in a fork you are authorized to use, and submit pull requests, including unsolicited ones. Without a recognized reservation, keep the work independent and disclose conflicts; do not act in an owner's checkout, use someone else's credentials or budget, or claim exclusive custody.
  • A recognized holder stays within the granted scope and current generation. Submission and review retain custody but are not acceptance; expiry starts reconciliation rather than silent reassignment.

Work and verify

Use a branch in your authorized fork and keep changes within the issue's criteria. Read AGENTS.md and the task-specific guides it routes to. For testing boundaries and repository gates, use the verification guide; for issue/project operations, use the github-workflow skill. To set up a fresh checkout and find your path's focused checks, follow Contributor readiness.

When a task involves operating Pohunek itself, reuse the shipped Pohunek agent skill for its CLI and safety contract. This contribution guide does not replace that operating guidance.

Run the issue's focused checks and every applicable repository gate. Tie each result to the exact candidate commit and base. Report checks as passed, failed, skipped with a reason, or unverified; never present unknown or skipped evidence as green. Include generated artifacts and relevant compatibility evidence when the issue requires them.

Submit and hand off

Open a pull request from your authorized fork using the public pull-request template, targeting the repository's default branch. A pull request into this repository can only use one of its own branches as the base, so a fork cannot target the branch of a preceding slice. Split larger work into the slices described by the stacked PR workflow and keep one slice open at a time: prepare the next slice on its own branch, and open its pull request only after the slice below it lands. Use Refs #NUMBER for a non-final slice; use Closes #NUMBER only on the final slice when the issue's full definition of done is met. GitHub web or gh pr create --repo zajca/pohunek --base main are both available paths. Creating a pull request from a fork does not require write access to this repository; use only an account and fork you are authorized to use. Until a contributor has a merged contribution, each workflow run on their pull requests waits for maintainer approval.

In the PR, provide the candidate SHA, base SHA, issue criteria, exact check commands and outcomes, unresolved work, and the next permitted action. Request review through the public route defined in Public contributions and authority: the maintainer zajca triages, routes, and integrates after the required gates and independent review, and an available independent reviewer examines the code, contract, and evidence of the exact candidate. If no independent reviewer is available, the candidate stays unaccepted until routing succeeds. You cannot supply independent approval for your own work, including through another session or agent used to author it; only a fresh review-only session that did not author the change supplies the marker below. The technical review gate is defined in contributionPolicy.reviewAndIntegration.automatedReview; for each head of your pull request:

  1. The maintainer approves the workflow runs for that head.
  2. The maintainer's manager requests an Opus review of that head.
  3. The result arrives as a pull request comment authored by zajca that carries the opus-pr-review:v1 marker at the exact head. A marker from any other author does not count, and no label is needed. GO is high=0 and medium=0; LOW-only findings pass and become follow-up issues.
  4. If no review has arrived some hours after green CI, mention the maintainer on the pull request.

The marker is the technical gate only: merging an outside contribution also needs the maintainer's explicit approval. Every new head needs its own marker, and an interrupted run is not approval. The CI checks that must be green on the head are listed under Required checks. Review grants no merge authority; release is separately authorized. Apart from the maintainer-approved, read-only pull_request run, your fork head is never dispatched, run through a ref such as refs/pull/<N>/head, or rerun by an agent in this repository. For a pull request that needs tier=main or release evidence, the maintainer reviews the full diff, workflow files included, and re-creates the change on a maintainer branch and dispatches it, or relies on a later run on main: the post-merge run covers the main tier, while the release rehearsal and the other nightly-only jobs get evidence only from the scheduled nightly run or a tier=nightly dispatch (Fork heads in .agents/instructions/verification.md).

For a handoff, record the issue/spec revision, current reservation and identity generation when applicable, exact branch/commit/PR, actual checks, unresolved effects, and next permitted action in public evidence. An acknowledgment alone does not transfer custody. Follow the same rules for unsolicited competing pull requests; a reservation guarantees no merge.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.