docs: add AI agent contribution guidance by jatmn · Pull Request #1676 · Twigpine/openclaude

jatmn · 2026-06-16T18:13:46Z

Summary

add AGENTS.md with repository-specific guidance for AI coding agents
update CONTRIBUTING.md with maintainer-directed contribution expectations and a link to AGENTS.md

Impact

user-facing impact: none; documentation-only change
developer/maintainer impact: gives AI-assisted contributors clearer project rules, validation guidance, provider-change expectations, and limits on new Python work

Testing

not run; documentation-only change

Notes

provider/model path tested: not applicable
screenshots attached: not applicable
follow-up work or known limitations: none

Summary by CodeRabbit

Documentation
- Added comprehensive guide for AI agents covering repository structure, coding conventions, validation commands, and provider-change procedures.
- Updated contributing guidelines with refined expectations, including feature proposal policies, automated PR review standards, and contributor conduct requirements.

Add AGENTS.md with repository-specific guidance for AI coding agents, including runtime conventions, validation commands, provider-change expectations, and limits on new Python work. Update CONTRIBUTING.md with maintainer-directed contribution expectations, CodeRabbit follow-up requirements, duplicate PR guidance, and a link to AGENTS.md.

coderabbitai · 2026-06-16T18:15:20Z

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: a565cfb0-a3bb-4163-9f9b-2de1057dc4f1

📥 Commits

Reviewing files that changed from the base of the PR and between 5c0e661 and 2f64aa9.

📒 Files selected for processing (2)

AGENTS.md
CONTRIBUTING.md

📜 Recent review details

🧰 Additional context used

📓 Path-based instructions (4)

**/*.{ts,tsx,js,jsx,py,json,md,yml,yaml}

📄 CodeRabbit inference engine (CONTRIBUTING.md)

Follow the existing code style in the touched files

Files:

CONTRIBUTING.md
AGENTS.md

**/*

⚙️ CodeRabbit configuration file

**/*: Apply the OpenClaude maintainer review rubric from AGENTS.md. Review the current diff, not stale discussion context. Separate real blockers from suggestions. Do not request changes for vague style churn. Treat approval as merge-ready from CodeRabbit's side, pending required human review and GitHub Checks. If checks are failing or unavailable, say so clearly instead of implying the PR is fully ready.

Files:

CONTRIBUTING.md
AGENTS.md

{README.md,CONTRIBUTING.md,docs/**,.github/pull_request_template.md}

⚙️ CodeRabbit configuration file

{README.md,CONTRIBUTING.md,docs/**,.github/pull_request_template.md}: Review docs for accuracy against current code behavior. Flag security or provider claims that overpromise, stale install commands, missing setup caveats, and instructions that could push users toward unsafe credential handling. Keep purely wording-level suggestions non-blocking.

Files:

CONTRIBUTING.md

**

⚙️ CodeRabbit configuration file

**: # Contributing to OpenClaude

Thanks for contributing.

OpenClaude is a fast-moving open-source coding-agent CLI with support for multiple providers, local backends, MCP, and a terminal-first workflow. The best contributions here are focused, well-tested, and easy to review.

Before You Start

Search existing issues and discussions before opening a new thread.

Check open pull requests for work that overlaps with your contribution. If a PR already exists that addresses the same change, open an issue or discussion first to align on direction — duplicate PRs may be closed without review.

Use issues for confirmed bugs and actionable feature work.

Use discussions for setup help, ideas, and general community conversation.

For larger changes, open an issue first so the scope is clear before implementation.

For security reports, follow SECURITY.md.

Pull Requests

Every PR needs a reason. Your PR description must include:

what changed and why

the user or developer impact

the exact checks you ran

a linked issue when one exists, using Fixes fix: skip assertMinVersion for third-party providers #123, `Closes `#123, or another clear link

screenshots when the PR touches UI, terminal presentation, or the VS Code extension

which provider path was tested when the PR changes provider behavior

The PR author is responsible for ensuring their PR is merge-ready. PRs with merge conflicts will not be reviewed or approved until the conflicts are resolved.

Issues are the recommended starting point for anything non-trivial — opening one first helps avoid wasted effort if the change is out of scope or already being worked on. Small fixes, doc corrections, and obvious improvements can stand on their own without a linked issue, as long as the PR description explains the intent.

What Gets Closed Without Review

PRs may be closed without review...

Files:

CONTRIBUTING.md
AGENTS.md

🧠 Learnings (1)

📓 Common learnings

Learnt from: CR
Repo: Gitlawb/openclaude

Timestamp: 2026-06-16T18:15:01.787Z
Learning: Keep changes focused on one problem; avoid unrelated formatting, renames, dependency changes, or broad rewrites

Learnt from: CR
Repo: Gitlawb/openclaude

Timestamp: 2026-06-16T18:15:01.787Z
Learning: Prefer existing patterns in the file or nearby module rather than introducing new abstractions

Learnt from: CR
Repo: Gitlawb/openclaude

Timestamp: 2026-06-16T18:15:01.787Z
Learning: Do not skip tests for behavior changes

Learnt from: CR
Repo: Gitlawb/openclaude

Timestamp: 2026-06-16T18:15:01.787Z
Learning: Use existing service, provider, settings, permission, and UI patterns over creating new abstractions

Learnt from: CR
Repo: Gitlawb/openclaude

Timestamp: 2026-06-16T18:15:01.787Z
Learning: Run core validation checks including bun install, bun run build, bun run smoke, bun run check, bun run typecheck, and bun run typecheck:type-tests

Learnt from: CR
Repo: Gitlawb/openclaude

Timestamp: 2026-06-16T18:15:01.787Z
Learning: Avoid breaking third-party providers while fixing first-party behavior

Learnt from: CR
Repo: Gitlawb/openclaude

Timestamp: 2026-06-16T18:15:01.787Z
Learning: Do not ignore CodeRabbit or maintainer feedback; address it before requesting more review

Learnt from: CR
Repo: Gitlawb/openclaude

Timestamp: 2026-06-16T18:15:19.066Z
Learning: Prefer small, readable changes over broad rewrites

Learnt from: CR
Repo: Gitlawb/openclaude

Timestamp: 2026-06-16T18:15:19.066Z
Learning: Do not reformat unrelated files just because they are nearby

Learnt from: CR
Repo: Gitlawb/openclaude

Timestamp: 2026-06-16T18:15:19.066Z
Learning: Add or update tests when the change affects behavior

Learnt from: CR
Repo: Gitlawb/openclaude

Timestamp: 2026-06-16T18:15:19.066Z
Learning: Keep PRs focused on one problem or feature; avoid mixing unrelated cleanup into the same change

Learnt from: CR
Repo: Gitlawb/openclaude

Timestamp: 2026-06-16T18:15:19.066Z
Learning: Preserve existing repo patterns unless the change is intentionally refactoring them

Learnt from: CR
Repo: Gitlawb/openclaude

Timestamp: 2026-06-16T18:15:19.066Z
Learning: Review generated code thoroughly before opening a PR, checking for correctness, style consistency, and adherence to project patterns

Learnt from: CR
Repo: Gitlawb/openclaude

Timestamp: 2026-06-16T18:15:19.066Z
Learning: Do not assign or use provider tags in PRs; these are controlled by maintainers

Learnt from: CR
Repo: Gitlawb/openclaude

Timestamp: 2026-06-16T18:15:19.066Z
Learning: PR descriptions must include what changed and why, user or developer impact, exact checks run, and linked issues using Fixes `#123` or Closes `#123`

Learnt from: CR
Repo: Gitlawb/openclaude

Timestamp: 2026-06-16T18:15:19.066Z
Learning: Address CodeRabbit findings before waiting for maintainer review; PR authors must respond to automated review feedback

Learnt from: CR
Repo: Gitlawb/openclaude

Timestamp: 2026-06-16T18:15:19.066Z
Learning: Respond to review feedback within 1 week of a maintainer or CodeRabbit review request

Learnt from: CR
Repo: Gitlawb/openclaude

Timestamp: 2026-06-16T18:15:19.066Z
Learning: Search existing issues and open PRs before opening a new thread to avoid duplicate work

Learnt from: CR
Repo: Gitlawb/openclaude

Timestamp: 2026-06-16T18:15:19.066Z
Learning: For larger changes, open an issue first so the scope is clear before implementation

Learnt from: CR
Repo: Gitlawb/openclaude

Timestamp: 2026-06-16T18:15:19.066Z
Learning: Before investing time in a feature PR, open an issue first to propose and discuss your idea with maintainers

Learnt from: CR
Repo: Gitlawb/openclaude

Timestamp: 2026-06-16T18:15:19.066Z
Learning: Run 'bun run check' (smoke + unit tests) locally before pushing

Learnt from: CR
Repo: Gitlawb/openclaude

Timestamp: 2026-06-16T18:15:19.066Z
Learning: Run 'bun run test:full' for single concurrency test pass matching CI before submission

Learnt from: CR
Repo: Gitlawb/openclaude

Timestamp: 2026-06-16T18:15:19.066Z
Learning: Stay within the project's existing technical direction and avoid shifting the codebase to a new language or significantly restructuring dependencies without prior discussion

🪛 LanguageTool

AGENTS.md

[style] ~32-~32: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ...erfor CLI argument parsing. -execa` for child processes. - Existing service, pr...