AI Agent Support

Every project generated by Archipelago includes AI agent configuration out of the box. There is nothing to set up — the configs are generated alongside your code and contain accurate information about your specific project structure.

Overview

The flutter_modular_monorepo brick generates dedicated config files for every major AI coding assistant. Each file is pre-populated with your project's workspace layout, architecture patterns, key commands, and conventions — so agents can start helping immediately without requiring manual context.

File	Tool	Generated When
CLAUDE.md	Claude Code	Always
AGENTS.md	OpenAI Codex and generic agents	Always
.cursorrules	Cursor IDE	Always
.github/copilot-instructions.md	GitHub Copilot	When gitProvider is github (the default)
.claude/commands/	Claude Code slash commands (8)	Always
.claude/skills/	Agent skills, indexed in AGENTS.md	Always; some bricks add their own
.mcp.json	Claude Code MCP servers (Marionette)	Always

Project Context Files

CLAUDE.md — Claude Code

Located at the project root, CLAUDE.md gives Claude Code a complete picture of your workspace before any conversation begins. It covers:

• Workspace directory layout (apps/, features/, infrastructure/, shared/, etc.)
• Architecture patterns: API/Impl split, Impl + Noop, Dual-GetIt, FeatureSDK self-registration, two-phase init
• Telemetry consent and PII scrubbing, and locale persistence
• Common melos commands for building, testing, formatting, and build_prepare swaps
• Environment setup for a cold start
• Dart and commit conventions used across the monorepo
• Step-by-step guides for adding a feature or infrastructure package

AGENTS.md — Generic Agent Support

AGENTS.md provides a short project overview in a vendor-agnostic format, compatible with OpenAI Codex and any agent that looks for a top-level AGENTS.md file. It lists the agent-specific config files, the key patterns, essential commands and do/don't rules, and points to CLAUDE.md as the single source of truth. It also holds the skill index: one row per skill in .claude/skills/, so an agent that does not load skills by itself knows which guide to read.

.cursorrules — Cursor IDE

.cursorrules delivers a condensed architecture and convention reference in Cursor's expected format, with a pointer to CLAUDE.md for the full documentation.

.github/copilot-instructions.md — GitHub Copilot

When you generate a project with gitProvider: github (the default), Archipelago also creates .github/copilot-instructions.md. GitHub Copilot reads this file automatically and applies the instructions to all suggestions and chat responses in the repository.

TIP

If you start with a non-GitHub project and later move to GitHub, you can add this file manually by copying the content from .cursorrules or AGENTS.md into .github/copilot-instructions.md.

Drive the running app (Marionette MCP)

Generated apps ship LeanCode Marionette in debug builds. An agent connected to the marionette_mcp server can read the widget tree, tap, enter text, scroll, take screenshots and read the app's logs, so it can check its own UI change in the running app.

Debug builds only. bootstrap.dart calls ensureAppBinding(...) from features/app_marionette/app_marionette before anything else. It installs MarionetteBinding when kDebugMode, and the plain binding under flutter test or when an integration or Patrol test already installed one. Every release and profile build, of any flavor, swaps the package for app_marionette_noop (build-prepare --mode release, the debug_build_only list), and --check-leaks fails if marionette_flutter is still resolved. See Build Prepare.

Connect:

1. Once per machine: dart pub global activate marionette_mcp.
2. The generated .mcp.json registers the marionette server for Claude Code. For another tool, or without the file: claude mcp add --transport stdio marionette -- marionette_mcp.
3. Run the app in debug: cd apps/<app> && flutter run --flavor development -t lib/main_development.dart.
4. Copy the VM service URI that flutter run prints (ws://127.0.0.1:<port>/<token>=/ws) and ask the agent to connect to it. It then uses get_interactive_elements, tap, enter_text, scroll_to, take_screenshots and get_logs.

The UI kit's buttons, text fields, OTP/PIN inputs and checkbox are reported under their kit names through isUiKitInteractive in the kit. Add a new interactive kit control there. Logs written through the app's Log (package:logger) reach get_logs. The generated CLAUDE.md and AGENTS.md repeat these steps for the agent.

Claude Code Slash Commands

Claude Code users get 8 domain-specific slash commands generated into .claude/commands/. Each command is a focused guide that Claude Code follows as a step-by-step task — far more reliable than asking in free-form chat.

Command	What it does
/workspace-health	Checks that all packages resolve, analyze cleanly, and tests pass
/add-feature	Scaffolds a new feature module following FeatureSDK conventions
/add-infrastructure	Adds an infrastructure SDK with the correct API/Impl split
/architecture-guide	Returns a reference for architecture decisions and package boundaries
/build-prepare	Guides you through swapping debug/release dependencies via build_prepare
/manage-flavors	Walks through adding or updating app flavors
/deploy	Test builds and store releases: Fastlane lanes, the mobile/v* release tag, secrets, the build-prepare hooks
/changelog	Writes a CHANGELOG.md entry from the commits since the last tag

Run any command from within your project in Claude Code:

/workspace-health
/add-feature profile
/add-infrastructure analytics

Agent Skills

Skills are task guides in .claude/skills/<name>/SKILL.md. Claude Code loads one when the task matches its description. Other agents find them through the skill index in AGENTS.md.

A skill ships with the brick that owns the capability it describes. A brick that is not in your project adds no skill, so a project only gets the skills for what it has. When you generate such a brick later, its post_gen hook writes the skill and adds its row to the index.

Skill	Ships with	Used when
feature-di-registration	flutter_modular_monorepo	Creating or wiring a feature SDK, adding DI registration, or debugging a feature whose routes or SDK never appear at runtime
generator-markers	flutter_modular_monorepo	Editing bootstrap.dart, initializer files, the injector, build_prepare.yaml or any file with archipelago: comment markers
ui-kit-conventions	flutter_modular_monorepo	Building or editing widgets, pages or themes: colors, text styles, spacing and assets come from the UI kit context extensions, never Theme.of(context)
ci-triage	flutter_modular_monorepo	A CI run failed, was skipped or tested the wrong packages, or before you change the generated CI
archipelago-upgrade	flutter_modular_monorepo	Running a brick again, a brick that stopped with Nothing was changed, archipelago upgrade, or the files in .archipelago/
brand-assets	asset_optimizer (Pro)	Drawing brand art as code (SVG icons and illustrations, python-lottie animations, festive logo, app icon and splash variants), converting Lottie .json to .lottie and back, and wiring art into the asset package and Widgetbook. See the showcase
blackbox-sessions	app_blackbox_recorder (Enterprise)	Reading a Blackbox .bbx session to explain jank, slow screens, memory or CPU growth, file activity or a slow launch, and adding Blackbox events and markers

How It Works

All agent config files are plain Markdown. They are written as part of the flutter_modular_monorepo brick template, so they are generated at the same time as your project scaffolding. Because they come from the same source as the rest of the brick, the instructions always match the actual code structure.

The generated files are yours to modify. As your project evolves — new packages, different conventions, updated commands — you can update CLAUDE.md and the slash commands to reflect the current state of the codebase. A brick that ships a skill rewrites its own skill folder when you run it again, so keep project-specific notes in CLAUDE.md rather than in a brick's skill.

Keep them in version control

Commit all agent config files. When teammates clone the repo, they get the same AI context immediately. CI agents (such as GitHub Actions workflows that use Claude or Copilot) also benefit from these files being present.

Supported Tools at a Glance

Tool	File	Notes
Claude Code	CLAUDE.md + .claude/commands/ + .claude/skills/	Slash commands and skills for monorepo tasks
Cursor	.cursorrules	Auto-loaded by Cursor on open
GitHub Copilot	.github/copilot-instructions.md	Requires gitProvider: github
OpenAI Codex	AGENTS.md	Standard agent instructions file
Any agent supporting AGENTS.md	AGENTS.md	Vendor-agnostic fallback