docs(Agents): Establish contribution guidelines for AI agents

[emyller]

Establishes comprehensive guidelines for AI agentic contributions to the repository, as a result of experimentation in multiple kinds of products and goals.

[!WARNING] This is a very opinionated WIP, and is subject to morph into something completely different (again). We're still experimenting with our AI agent(s) of choice, and discussing internally about what works best and in full alignment with our team of human beings.

This is intended to become a framework that helps engineers at Flagsmith to achieve:

1. Faster [human] context collection (for better [human] decision making)
2. Consistency across AI-assisted work
3. Reducing of review burden
4. Assisted writing of technical documentation, e.g. issues
5. Substantial productivity boost with assisted development
6. Reliable vibe-coding capabilities for building PoCs
7. Overall better DevEx with the AI agent
8. Efficient use of time and planet resources by AI

A key in this experiment is hacking the agent with a compliance report that helps building longer-term confidence with minimal context loss. Such a report is generated prior to every action suggested by AI, and presented to the user for their confirmation or steering. e.g.:

Compliance Report #47
Action: Add test for SegmentOverrideDeleteView 404 response
- Writing Style: N/A (no prose output)
- Technical Conduct: 5/5 (read existing test patterns in test_views.py)
- Git Operations: N/A (not staging yet)
- Commit Messages: N/A (not committing yet)
- Issues and Pull Requests: N/A (no issue or PR)
- Push and PR Workflow: N/A (no push)
- PR Reviews: N/A (no PR review)
- Documentation and Comments: N/A (no docstrings added)
- Code Architecture: 5/5 (followed existing test fixtures and assertions)
- Online Research: N/A (no external research)
- Testing: 5/5 (Given/When/Then structure, single behaviour, descriptive name)
- Conversation: N/A (no user-facing prose)

(Command, file change, or any other request for user approval)

Changes

• [x] Define compliance protocol with scoring system and abort conditions
• [x] Summarise Red Hat Technical Writing Style Guide rules for writing style, punctuation, and lists
• [x] Document scope boundaries and technical conduct requirements
• [x] Specify git operations, commit message, and branch naming conventions
• [x] Define issue and PR title formats with examples
• [x] Establish push restrictions and PR creation workflow
• [x] Establish PR review workflow with explicit user coordination
• [x] Add documentation and code comment guidelines
• [x] Define code architecture principles and dependency selection criteria
• [x] Establish online research requirements with version verification
• [x] Specify testing structure and coverage requirements
• [x] Add conversation rules to enforce honesty and prevent flattery

Review effort: ?/5 (WIP)

---

Examples of this in action. (WIP)

Refusing action

This screenshot demonstrates two very important features:

1. AI does not assume a question to be a request.
2. AI refuses to violate guidelines.

Context collection

This example is of an update to an issue that was pending due to the author's own lack of opportunity to visit it. AI follows patterns of writing style, and offers a workflow to the user after working on its own for 5 minutes. One iteration.

[cursor[bot]]

You have run out of free Bugbot PR reviews for this billing cycle. This will reset on December 10.

To receive reviews on all of your PRs, visit the Cursor dashboard to activate Pro and start your 14-day free trial.

[vercel[bot]]

The latest updates on your projects. Learn more about Vercel for GitHub.

3 Skipped Deployments

Project	Deployment	Review	Updated (UTC)
docs	Ignored	Preview	Dec 18, 2025 3:03pm
flagsmith-frontend-preview	Ignored	Preview	Dec 18, 2025 3:03pm
flagsmith-frontend-staging	Ignored	Preview	Dec 18, 2025 3:03pm

[github-actions[bot]]

Docker builds report

Image	Build Status	Security report
ghcr.io/flagsmith/flagsmith-api-test:pr-6291	Finished :white_check_mark:	Skipped
ghcr.io/flagsmith/flagsmith-e2e:pr-6291	Finished :white_check_mark:	Skipped
ghcr.io/flagsmith/flagsmith-frontend:pr-6291	Finished :white_check_mark:	Results :white_check_mark:
ghcr.io/flagsmith/flagsmith-api:pr-6291	Finished :white_check_mark:	Results :white_check_mark:
ghcr.io/flagsmith/flagsmith:pr-6291	Finished :white_check_mark:	Results :white_check_mark:
ghcr.io/flagsmith/flagsmith-private-cloud:pr-6291	Finished :white_check_mark:	Results :white_check_mark:

[emyller]

Thanks for the early [great] reviews here guys. All comments are accounted for and will be addressed with time; this is a side project and it's been morphing into different things according to learning and experience. We'll discuss and play around together before eventually merging.

[Zaimwa9]

By the way, sharing some resources in this PR: https://www.humanlayer.dev/blog/writing-a-good-claude-md

[emyller]

By the way, sharing some resources in this PR: https://www.humanlayer.dev/blog/writing-a-good-claude-md

@Zaimwa9 Thanks — this is a great article. It has contributed to the feeling that I'm abusing the role of AGENTS.md in this PR. Nevertheless, the outcome of this experiment is proving excellent. This might turn into something else: [a chain of?] system prompts, or a new model entirely.