[all] support for AI coding agents

[r0ssing]

Component

• formulus (React Native mobile app)
• formulus-formplayer (React web app)
• synkronus (Go backend server)
• synkronus-cli (Command-line utility)
• Documentation
• Other (please specify)

Feature Description

Introduce first-class support for AI coding agents across the monorepo to improve developer productivity and onboarding. This includes standardized AGENTS.md guidance files and optional custom "skills" or task-specific instructions where appropriate for each component.

The goal is to make it easier for AI assistants (e.g., Claude, ChatGPT, Cursor, etc.) to understand project conventions, architecture, workflows, and common development tasks.

Problem Statement

AI-assisted development is becoming a normal part of engineering workflows. However, without structured guidance, agents often lack context about:

• repository structure
• architectural decisions
• development workflows
• build/test commands
• coding conventions
• cross-component interactions

In a multi-component monorepo this leads to inconsistent suggestions, wasted time explaining the same context repeatedly, and occasional incorrect changes.

Proposed Solution

Add standardized AI-agent support across the repository:

1. Repository-level AGENTS.md

   • High-level overview of the monorepo
   • Architecture description
   • How the components interact
   • Shared development workflows

2. Component-level AGENTS.md (where useful)

   • Local architecture and conventions
   • Key directories
   • Typical development tasks
   • Testing and build commands

3. Custom agent "skills"
   Where useful, define reusable instructions for common tasks such as:

   • generating form definitions
   • working with the Synkronus API
   • debugging React Native issues
   • adding new CLI commands

4. Documentation updates

   • Explain how developers can use AI agents effectively in this repository
   • Document the purpose and conventions of AGENTS.md

The implementation should remain lightweight and documentation-focused so it does not introduce maintenance burden.

Alternatives Considered

• Doing nothing and relying on developers to provide context manually
• Adding ad-hoc prompts or instructions in various documentation pages

Both approaches tend to fragment knowledge and make AI-assisted workflows less reliable.

Additional Context

Several tools and editors now support repository-level guidance files for AI agents. Establishing these conventions early should make the codebase more accessible for both human and AI contributors as the project grows.

[m13v]

interesting challenge - we've been running parallel AI coding agents against shared codebases and the hardest part is conflict resolution when two agents edit overlapping files. git worktrees help isolate each agent's workspace but you still need a merge strategy. for formulus/synkronus specifically, having clear module boundaries would make agent support much easier since each agent can own a component without stepping on others.

[m13v]

for reference, here's how our desktop automation framework handles the element-level isolation that makes parallel agent access possible - each agent gets its own element tree: https://github.com/mediar-ai/terminator/blob/main/crates/terminator/src/element.rs

and the core lib that manages concurrent access to desktop state: https://github.com/mediar-ai/terminator/blob/main/crates/terminator/src/lib.rs