Create AGENTS.md

create-agents-md — generate or refresh an AGENTS.md

Produce a prescriptive AGENTS.md grounded in source. Every claim MUST trace to a real function name, table name, import path, or file — grep and verify; never describe what "might" exist.

Announce at start: "Using the create-agents-md skill — generating/refreshing the AGENTS.md for {target}."

Step 1: Identify the target

• Package: packages/{name}/ → budget ≤100 lines
• Module: apps/erp/app/modules/{name}/ → budget 60–100 lines

Step 2: Read the actual source

# Module:
ls apps/erp/app/modules/{name}/
grep -n "^export" apps/erp/app/modules/{name}/{name}.service.ts
grep -n "export const.*=.*z\." apps/erp/app/modules/{name}/{name}.models.ts
grep -rn "\.from(" apps/erp/app/modules/{name}/{name}.service.ts | sed 's/.*\.from("\([^"]*\)").*/\1/' | sort -u
grep -rn "\.rpc(" apps/erp/app/modules/{name}/ | sed 's/.*\.rpc("\([^"]*\)".*/\1/' | sort -u
grep -rn "requirePermissions" apps/erp/app/routes/x+/{name}* | head -10

# Package:
ls packages/{name}/src/
cat packages/{name}/src/index.ts
cat packages/{name}/package.json | jq '.exports'

Step 3: If refreshing, read the existing file

• Preserve human-added notes, warnings, and domain explanations.
• Update stale function/table/import names (verify each with grep).
• Add new exports/tables/patterns; remove references to deleted code.

Step 4: Read the relevant rules

Find the .ai/rules/ files that govern this area (via the root AGENTS.md Task Router) and reference them in the Rules References section — only files that actually exist.

Step 5: Write it

Module template

# {Module Name} Module

{One line: what this module does in the ERP domain.}

## Key Domain Concepts
{3–6 terms a non-manufacturing AI needs. **Term** — plain-English definition.
 Include status lifecycles.}

## Safety
### Always
- MUST {do X} — `{function/table}` depends on it.   {3–5 rules, grounded}
### Ask First
- {action} — {why risky}.                            {2–3 items}
### Never
- {action} — {what breaks}.                          {2–3 items}

## Validation Commands
```bash
pnpm exec turbo run typecheck --filter=erp
pnpm --filter erp test
```

## Key Data Model
| Table / View | Purpose |
|---|---|

## Key Service Functions
- `{functionName}` — {what it does}   {only what another module would call}

## Copy From   {OPTIONAL — only if this module is a good template}
| To build… | Copy from… | Then change… |

## Related Modules
- **{module}** — {integration point}

## Rules References
- `.ai/rules/{file}.md` — {what it covers}

Package template

# @carbon/{name}

{One line.}

## Always / Ask First / Never
{Same shape as the module template.}

## Validation Commands
```bash
pnpm --filter @carbon/{name} typecheck
pnpm --filter @carbon/{name} test
```

## Key Exports
| Subpath | Provides |
|---------|----------|
| `.` | {…} |          {real subpaths from package.json exports}

## Cross-References
{rules, related packages, consuming apps}

Done when — verify each line

• Every function name exists: grep -n "export.*{name}" {file} hits
• Every table name exists: grep in the service file hits
• Every import path is real (check the barrel / exports field)
• Every referenced .ai/rules/ file exists
• Tone is prescriptive ("MUST use X"), not descriptive ("X is used")
• Line count within budget; no {placeholder} / TBD left
• Modules: Key Domain Concepts present; Never section present
• Refresh: human-added notes preserved

Anti-patterns

• Listing functions you didn't grep for (renamed/deleted ones will lie)
• Abstract architecture prose ("uses a service layer" says nothing)
• Copying a sibling AGENTS.md and renaming — every module has different tables, functions, and concepts
• Vague bullets: "Services handle data access" ❌ vs "MUST use insertManualInventoryAdjustment for quantity changes — it creates ledger entries and updates tracked entities" ✅