For Engineering

Laurelin agents

Five specialized Claude agents handle Laurelin tasks. They live in the valinor_claude repo, not this one — keeping the agent definitions there lets us version the prompts independently of the application code.

The agents

Agent	Role
laurelin-database	Schema work, migrations, audit-aware data fixes. Reads `db.js`, proposes column changes, runs against a snapshot first.
laurelin-ui	Frontend changes in `apps/laurelin.jsx`. Knows the styling system, the tab structure, the `api()` helper, and the existing view conventions.
laurelin-architect	Higher-level design work — new features, refactors that span backend + frontend, decisions about whether to add a route vs extend an existing one.
laurelin-discovery	External research. Used when working on a deal/diligence and needing to populate company metadata from public sources.
laurelin-supervisor	Coordinates the others on multi-step tasks. Hands off database changes to `laurelin-database`, UI changes to `laurelin-ui`, etc. The "PM" of the agent set.

Finding the definitions

VALINOR_REPO=$(find ~ -maxdepth 4 -name "laurelin-database.md" -path "*/.claude/agents/*" \
  -not -path "*/worktrees/*" 2>/dev/null | head -1 | sed 's|/.claude/agents/laurelin-database.md||')
echo "Valinor repo: $VALINOR_REPO"
ls "$VALINOR_REPO/.claude/agents/"

This is the canonical locator — run it from anywhere with the Valinor repos cloned. The agents are typically in ~/valinor_claude/.claude/agents/.

The safety rules

$VALINOR_REPO/.claude/rules/laurelin-safety.md is the cross-agent rules file. It contains:

Canonical enum values (so all agents agree on what a valid stage or deal_stage is).
The audit-logging requirement (logChanges() on every companies/people/projects UPDATE).
The "never push to main without a PR" rule (agents push to claude/... branches).
The "back up the DB before schema changes" rule.
The list of files agents are not allowed to touch without explicit user direction (typically the deploy script, systemd units, and OAuth secrets).

Read this file when onboarding a new agent or modifying any existing one — it sets the floor.

When to invoke which

You want a new endpoint or table → laurelin-architect first for the design, then laurelin-database + laurelin-ui to implement.
You want a UI tweak (a new filter, a tab reorganization) → laurelin-ui directly.
You want a data fix (a misrouted interaction, a company merge gone wrong) → laurelin-database. It will read the audit trail and propose a backed-out change.
You're doing diligence on a company and want pre-populated context → laurelin-discovery. Returns research notes; doesn't write to Laurelin without explicit handoff.
You're not sure → laurelin-supervisor. It will route.

The agents are invoked from Claude Code in the parent repo. They're not built into Laurelin itself — they're tools we use to operate Laurelin.

Agent ergonomics

Each agent has its full system prompt in the markdown file. Common patterns across all five:

They read the schema before writing SQL. cat laurelin/db.js | head -200 is in every prompt.
They snapshot the DB before any change with scripts/backup-laurelin.sh pre-agent-<task>.
They write to a feature branch (e.g., claude/add-tag-filtering) and create a PR. No agent ever pushes to main directly.
They include the schema-doc regeneration in their commit when schema changes.

If an agent does something it shouldn't, the recovery path is git revert <commit> + restore the DB from the pre-task snapshot.

Updating an agent

Edit the markdown file in $VALINOR_REPO/.claude/agents/. Commit. The agent is updated for the next invocation. No deploy, no restart — the agent's "code" is its prompt.

A good rule: when you find yourself correcting the same agent on the same kind of mistake twice in a row, update the agent definition rather than correcting it again.

What the agents are not

They're not autonomous. None of them run on a schedule. They wait for invocation.
They're not exposed to the public Laurelin URL. Agents run from your dev machine, against the SQLite DB on ValinorPC via SSH or against a local snapshot.
They don't have separate API credentials. They run as your Claude Code session — your auth, your permissions.