docs(conventions): require agent-relay github primitive for PR creation

[khaliqgant]

Summary

• Adds a new mandatory convention to AGENTS.md (and via symlink CLAUDE.md): when a workflow owns the PR-creation boundary, it MUST use @agent-relay/github-primitive rather than shelling out to gh pr create.
• Names the two entry points: declarative (createGitHubStep from @agent-relay/github-primitive/workflow-step with action: 'createPR') and imperative (GitHubClient.create({ runtime: 'auto' }) then client.createPR(...)).
• Recommends master/orchestration workflows include a final-pr step by default; specs must opt out explicitly.

Why

The primitive handles runtime selection (local gh vs Nango cloud vs relay-cloud proxy) and produces structured outputs the orchestrator can chain on. Raw gh pr create is opaque to the workflow runner and won't reliably work in cloud / no-gh environments. Discovered while diagnosing why a master orchestration that completed seven implementation slices left the user without a PR — the master spec had no PR-creation step at all, and the conventions didn't explicitly mandate the primitive over gh.

Test plan

• AGENTS.md:195 reflects the new rule.
• No tooling change required; this is conventions-only.
• Future workflow generators should treat this as a default opt-in.

🤖 Generated with Claude Code

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 1b7adf92-89b3-491e-87bc-d597af1ec4d0

📥 Commits

Reviewing files that changed from the base of the PR and between 0bb2b97 and 5c5e10e.

📒 Files selected for processing (1)

• AGENTS.md

---

📝 Walkthrough

Walkthrough

This PR adds a documentation convention rule to AGENTS.md requiring workflows that create pull requests to use the @agent-relay/github-primitive package via specified patterns rather than invoking gh pr create directly. The addition documents both declarative and imperative usage patterns, runtime behavior, and structured output capabilities.

Changes

PR Creation Primitive Convention

Layer / File(s)	Summary
Documentation Convention AGENTS.md	New mandatory convention rule specifying required use of @agent-relay/github-primitive (createGitHubStep or GitHubClient) for PR creation in workflows, with notes on runtime selection and structured outputs.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐰 A single line hops into the fray,
Documentation leads the way,
PR primitives now have their place,
A convention to embrace! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately summarizes the main change: adding a documentation convention requiring the agent-relay GitHub primitive for PR creation.
Description check	✅ Passed	The description thoroughly explains the convention addition, rationale, and test plan, all directly related to the AGENTS.md documentation changes.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/agents-md-pr-primitive

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no potential bugs to report.

View in Devin Review to see 1 additional finding.