Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
Repository guide for coding agents
Macro is a document and collaboration app with a Rust backend and a web frontend.
This file is the shared entry point: AGENTS.md symlinks to CLAUDE.md. Edit
CLAUDE.md and preserve the symlink; do not maintain two copies.
Start here
Unless the user says otherwise, before writing any code:
- Read CODING.md.
- Find the affected app, service, or crate in the map below and read its
AGENTS.md. - Read the task-relevant guides below, not every linked document.
- Explore the code you will change and its callers until you know how it works.
Rules in .agents/rules/ load when you touch matching files. Prefer them over
patterns in older code.
Repository map
| Path | Contents |
|---|---|
apps/web/ |
Web frontend; its own agent guide covers Bun, UI patterns, and browser verification. |
apps/, packages/ |
Other apps and shared frontend packages. |
services/ |
Deployable services and workers; Rust package names come from each Cargo.toml. |
crates/ |
Reusable backend libraries, domain services, and adapters. |
crates/macro_db_client/migrations/ |
MacroDB PostgreSQL migrations. |
infra/ |
Deployment definitions and local infrastructure. |
tooling/ |
Development tools, scripts, and imported just recipes. |
docs/ |
Development guides, architecture, designs, runbooks, and the browser agent guide; see the index. |
Where agent guidance lives
| Path | Contents |
|---|---|
CODING.md |
Coding rules for every language; read before writing code. |
AGENTS.md in a directory |
Scope, map, checks, and gotchas for that subtree; a sibling CLAUDE.md symlinks to it. |
.agents/skills/ |
Task workflows. Cursor loads this directory. .claude/skills and .pi/skills symlink here. |
.agents/rules/ |
Path-scoped conventions, loaded when you touch matching files. .claude/rules and .cursor/rules symlink here. |
.agents/agents/ |
Subagents (auditor, browser-verifier). .claude/agents symlinks here. |
.agents/templates/ |
Templates for new rules and AGENTS.md files. |
rules/ast-grep/ |
Mechanically enforced code rules, run by just check. |
Real files live in .agents/; tool-specific directories only symlink to it.
Read when relevant
| Task | Guide |
|---|---|
| Reusing database storage or separating it from an app entity | Database core skill |
| Adding collaborative markdown to a feature | Collab surface core skill |
| Editing frontend or backend code that adds a flow, view, or hot path, or tracing one | instrumentation skill |
| Finding slow web or desktop app flows in Datadog | perf-investigation skill |
| Adding, reading or removing a feature flag (web or backend) | feature-flags skill |
| Rust code, builds, or tests | Rust development |
| SQLx queries, migrations, DB tests, or cache errors | Database development |
| Web frontend | Web agent guide |
| iOS App Store releases, breaking Tauri changes, native build floors | iOS releases |
| Android Play releases from pull requests | Android development |
| Running CI on a pull request | CI on pull requests, run-ci skill |
| Email body rendering or snapshots | Standalone renderer |
| Running the frontend or backend on a local machine | Running locally |
| Giving the user a local preview link | local-preview skill |
| Working inside Cursor Cloud | Cursor Cloud |
| Driving the app through a browser | App agent guide |
| Agent MCP servers, including GoAlert | MCP servers |
| Adding or changing SDK methods | SDK rule, add-sdk-endpoint skill |
| SDK version bumps and npm publishing | SDK release guide, release-sdk skill |
| Adding a service, worker, or Pulumi stack | New service guide |
| Infrastructure, Pulumi, or deploys | Infrastructure guide |
Rules
Working with the user
- Do only what was asked. Questions get answers, not code changes.
- Commit as you go, in small logical commits on a feature branch, without
asking. Never commit to
main. Push or open a PR only when asked. Once authorized, finish in-scope review fixes and follow-up pushes without per-fix confirmation. - Keep each feature's development, validation, and local preview on one branch/worktree.
- Flag real risks; once the user decides, act on it.
- When the user gives improvement advice that applies beyond the current task, update the agent guidance it belongs in, in the same change (see Keeping guidance current).
- Disagree when they're wrong. No flattery.
- Answer simple questions directly.
- For UI work, ask how it should behave on mobile unless that's obvious.
- Ground UI proposals and prototypes in the existing Macro app screens and design system, preserving its shell, typography, controls, and spacing.
- Treat an approved UI proposal followed by a PR request as a request to implement it; keep standalone prototypes outside the repository unless asked.
- Be brief. No justification essays, no time estimates.
Environment
- Never touch production (data, services, consoles, secrets) without explicit permission.
- Never deploy (
pulumi up,wrangler deploy, workflow dispatch) without explicit permission for that deploy. - Never reset databases or wipe stack volumes without approval.
- Never paste or commit secrets, or put customer PII (emails, phones, addresses) in commits, PR titles, or PR descriptions.
- PR titles and bodies, commits, review replies, comments, and docs describe
only the code. Never name people, customers, their companies or products,
places, or support channels and tickets; state any reason in general terms.
See the
gitskill's Privacy section; CI'sPR Privacy Checkenforces it. - Never
git stash; it's shared across sessions. - Memory is context, not authority; verify against code.
- Treat hosted dev data as real.
.cursor/*.shis Cursor Cloud only. - Use
\cdinstead ofcd.
Before handing off
- Commits, branches, and PRs follow the
gitskill: Conventional Commit titles such asfix(onboarding): preserve team inputs, and Why / What bodies with no test plan. - Run the
auditskill (via theauditorsubagent) before saying work is done. - Update every doc your change makes stale, in the same change: the
AGENTS.mdof each directory you touched,docs/guides/,docs/architecture/, the agent guide, READMEs, rules, and skills. Search for the names you changed. - A new crate, service, or package gets an
AGENTS.mdfrom the template; one you change keeps itsAGENTS.mdcurrent. Add the sibling symlink (ln -s AGENTS.md CLAUDE.md) so Claude Code reads it too. - Open pull requests ready for review. If one is created as a draft, mark it ready for review before handing off.
- Run CI deliberately with the
run-cilabel (run-ciskill): at a checkpoint, a coherent locally tested chunk you want real CI on before building further, or when you think the PR is done. Never after every push, and never instead of local checks. A PR is done only whenCI gatepasses on its latest commit. - Test the affected packages/services individually before committing. Use the
relevant guide for setup; there is no root
just testrecipe. - For code changes, run
just check(format/lint/code rules scoped to changes).just check fulladds TypeScript checking and Rust clippy;just rust-checkis the workspace Rust type check. These checks do not replace tests. - Exercise user-visible changes in a browser. If routes, creation flows, editors, AI surfaces, or composer behavior change, update the corresponding app agent guide in the same change.
- Report what you tested and any checks blocked by the environment.
Keeping guidance current
Update the docs in the same change whenever:
- the user gives feedback that applies beyond the current task,
- you and the user settle on a new convention or reverse an old one,
- you find a doc, rule, or guide that is wrong or stale.
Put it in exactly one place, the narrowest that fits:
| Kind of guidance | Goes in |
|---|---|
| How to behave with the user, or a cross-cutting guardrail | This file, Rules |
| A coding rule for every language | CODING.md |
| A convention for certain paths (Rust, web, DB, infra) | .agents/rules/<area>/, from the rule template |
| Something checkable by a tool | An ast-grep rule in rules/ast-grep/ or a lint, instead of prose |
| Navigation, recipes, or gotchas for one directory | That directory's AGENTS.md, from the template |
| A repeatable multi-step task | A skill in .agents/skills/ |
| An end-to-end walkthrough of a change | docs/guides/ |
| How a system works | docs/architecture/ |
How:
- Edit the existing entry before adding a new one; delete what the change makes wrong. Never leave two versions of the same rule.
- Write the rule as one imperative line, with the reason only when it isn't obvious. ID-bearing rules take the next free number.
- Keep this file short: rules and links, no journals, command lists, or runbooks.
- Tell the user which doc you changed and how, in one line.