# Agent Rules

This repo is a lightweight Bloomreach Engagement strategy and content generator plus an optional runtime contentgen webhook backend. It does not own Bloomreach discovery, authentication, browser automation, or campaign asset creation. It consumes context, ranks/reworks CRM ideas, returns manual implementation guidance, and can serve generated email content JSON when the backend is explicitly started.

## Context Orchestration

Default path for this repo:

1. Start from the user task: strategy goal, segment request, scenario idea, content request, review, or symptom.
2. Use `docs/agent-context/router.md` to classify the task and choose the smallest useful context set.
3. Read `contexts/overview.md` first when unsure.
4. Load local business and strategy context only as needed:
   - `contexts/team.md`
   - `contexts/industries/<industry>.md`
   - `contexts/platforms/bloomreach.md`
   - `contexts/use-cases/<industry>.json`
   - `contexts/projects/<project>/project.md`, `schema.md`, `assets.md`, `events.json`, and `customer_properties.json`
5. Use supplied `projectContext` / `projectContextJson` as the live Bloomreach project evidence when Loomi MCP, a host agent, or the user provides it.
6. If Bloomreach CLI workspace context is available separately, use it as an optional richer project evidence source:
   - start with `context/context-router.md`
   - search `context/search-index.json`
   - prefer selected `context/cards/**/*.md`
   - open raw `context/*.json#<id-or-name>` only for exact selected-object fallback detail
7. Build a small task packet before generation: goal, task family, loaded context, exact project facts, assumptions, scope, and missing context.

Do not assume Bloomreach CLI workspace files exist in this repo. The built-in project context here is under `contexts/`; CLI card/raw orchestration applies only when those generated workspace files are present or supplied.

## Tools

- Use Context7 for current library, framework, SDK, API, CLI, and cloud-service documentation before implementing behavior that depends on those APIs.
- Use repository scripts and generator tools where available instead of ad hoc one-off logic.
- For complex multi-file changes, form a short plan before editing.
- For review requests, lead with bugs, regressions, risks, and missing tests.

## Git Practices

- Never commit directly to `main` or `master`; use a feature branch when committing.
- Do not force push unless explicitly asked.
- Keep commits focused and atomic.
- Before committing, ensure relevant tests pass and the code runs without obvious errors.
- Do not revert unrelated working-tree changes. Treat them as user work unless explicitly told otherwise.

## Code Quality

- Follow existing code style and local patterns.
- Keep functions small and focused.
- Use meaningful names.
- Remove dead code instead of commenting it out.
- Handle errors explicitly; do not silently swallow exceptions.
- Prefer structured APIs and parsers over brittle string manipulation.
- Add abstractions only when they remove real duplication or match an established local pattern.

## Safety

- This repo generates manual Bloomreach implementation guidance. Do not create, update, archive, delete, or launch Bloomreach campaign assets from this generator.
- Runtime catalog writes are allowed only through the contentgen backend when the user explicitly requests it and configures a write-capable catalog client; do not run that backend against a live project casually.
- Do not load, persist, or expose customer PII unless the user explicitly asks and the task truly requires it.
- Do not store credentials, browser session state, API keys, tenant secrets, raw customer records, or transient speculation as durable context.
- Include consent, suppression, frequency, and recent-conversion checks in CRM/scenario recommendations.
- Separate facts from assumptions and name missing context instead of inventing it.

## Verification

Before suggesting changes are complete:

- Run the relevant test suite when code or behavior changed.
- For docs-only changes, at least run `git diff --check`.
- Check imports, dependencies, and generated outputs when touched.
- Call out anything not verified.

## Project Surfaces

- Local MCP: `npm run mcp`
- Contentgen backend: `npm run serve`
- CLI generation: `npm run generate`
- Tests: `npm test`
- Context orchestration doc: `docs/context-orchestration.md`
- Agent router: `docs/agent-context/router.md`
- Strategy loop: `docs/strategy-loop.md`
- Bloomreach platform context: `contexts/platforms/bloomreach.md`

## Durable Context

If new project guidance, workflow behavior, or a repeated failure matters for future agents, update the relevant durable context:

- Repo/tooling behavior: `AGENTS.md`, `README.md`, or `docs/`.
- Business or client facts: `contexts/team.md` or project context under `contexts/projects/`.
- Bloomreach platform strategy: `contexts/platforms/bloomreach.md`.
- Skill workflow behavior: matching `skills/*/SKILL.md`.

Mention durable context updates in the final response.