Skip to content

docs: collaboration setup — issue templates, CONTRIBUTING, AGENTS, review labels, create-issue skill - #35

Draft
regislon wants to merge 1 commit into
mainfrom
collaboration-setup
Draft

regislon wants to merge 1 commit into
mainfrom
collaboration-setup

Conversation

@regislon

Copy link
Copy Markdown

Problem

The repo has no shared way of working yet: issues are free-form, there is no contribution guide, no rules for the AI agents that prepare many PRs, and nothing in the repo describes how main should be protected.

Change

  • Issue forms (.github/ISSUE_TEMPLATE/): Feature / improvement and Bug report, each with a single required Done when field (Must have / Nice to have) and closing tips; blank issues disabled. They use the existing enhancement and bug labels.
  • CONTRIBUTING.md: issues first for external contributors (core devs may open PRs directly), GitHub Flow into main, Conventional Commits titles (as the history already uses), PR description content, CI as the check gate, two-stage review.
  • AGENTS.md: the same rules written for AI coding agents, plus working principles (think first, keep it simple, surgical changes, verify).
  • Two-stage review with labels: an AI review sets llm-changes-needed or ready-for-human-review; needs-rebase is set and cleared by .github/workflows/needs-rebase-label.yml.
  • main ruleset (.github/rulesets/main.json), to import by hand: 1 approval, review threads resolved, lint-and-type + test passing on an up-to-date branch, no force-push/deletion, linear history.
  • create-issue agent skill (.agents/skills/create-issue/): tool-agnostic Agent Skills format, linked into .claude/skills/ for Claude Code and referenced from AGENTS.md for other tools. A script reads the issue forms at runtime and renders a body identical to a browser submission; the skill searches for duplicates, has the user confirm Done when, and only creates the issue on a clear yes.
  • .gitignore keeps .claude/skills/ tracked (the rest of .claude/ stays ignored); mdformat-frontmatter added to pre-commit so skill frontmatter survives formatting.

This was first set up and reviewed on our fork (AdAstraEco/cornerstone_luc#50) and is ported here unchanged except for the issue-template link.

Done when

Must have

  • Issue templates live on main (on merge)
  • Templates have a "Done when" section with must have vs nice to have
  • Maintainer creates the labels llm-changes-needed, ready-for-human-review and needs-rebase (the needs-rebase workflow fails to label until needs-rebase exists)
  • Repo admin imports .github/rulesets/main.json (Settings → Rules → Rulesets → Import a ruleset)
  • Repo admin enables Settings → General → Automatically delete head branches

Nice to have

  • Shared create-issue agent skill
  • More shared agent skills (create/sync PR, commit-and-push, review-pr)

Testing

  • pre-commit passes on all changed files; uv run pytest passes (1895 passed); the ruleset JSON and issue-form YAML parse.
  • create-issue render script tested on the fork: full render, missing required fields, unknown field, unknown template. Claude Code discovers the skill through the symlink; Codex / Gemini / Cursor discovery of .agents/skills/ not tested. No real issue was created.
  • GitHub only lists issue templates from main, so the chooser can be checked under New issue after merge; the needs-rebase workflow also only runs once on main.

Impact on outputs

None.

Dependencies

None. Open questions for the team:

  • AI attribution: AGENTS.md currently asks agents to state in the PR description that the PR was prepared with an AI agent, and which one. Keep, drop, or change?
  • Review flow: is the two-stage AI-then-human review with labels something you want here, or only the human-review half?

Prepared with Claude Code (Claude Opus 5.5).

🤖 Generated with Claude Code

…view labels, create-issue skill

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant