ElevateNow was running inefficiently. Founders POC'd features with Claude Code, then handed them to engineers who re-POC'd the same thing from scratch — burning time and API budget twice. There were no shared standards, no automatic safety checks, and nothing stopping a developer from accidentally breaking core architectural rules or hardcoding credentials.
- Founders POC with Claude Code locally — no shared context
- Engineers re-discover the same decisions from scratch
- No standard agent to call for a specific domain
- Code quality checks depend on whoever remembers to review
- No enforcement of architectural rules (GKR format, flat Tool_Chest, read-only backend)
- Token budget wasted on duplicate work and inefficient patterns
- Specialized agents live in every repo — clone = agents ready, zero setup
- Founders generate a handoff spec at POC end; engineers build from it
- 10 specialist agents cover every domain in the platform
- Supervisor CI auto-reviews every PR and posts a structured verdict
- Architecture violations blocked at the PR gate — never reach production
- Freshers cannot touch deploy files — enforced automatically
Agents are checked into git inside .claude/agents/ in each repository. The moment you clone the repo, Claude Code detects and loads them automatically. There is no install step, no sync script, and nothing to configure. Every team member who clones the same repo has the same fleet.
Three distinct roles interact with the fleet differently. The key change for everyone is that work flows through a handoff spec instead of verbal hand-offs — and quality is enforced automatically, not manually.
- POC features using Claude Code as before — no change to how you work day-to-day
- Use
@elevate-master-orchestratorfor multi-domain or cross-system decisions - At POC completion, the orchestrator generates a structured handoff spec capturing what was decided, which patterns were used, and what must not change
- Hand the spec to an engineer — they build from it, not from scratch
- Can view all PRs and all supervisor feedback across both repos
- Clone the repo — agents load automatically. No additional setup needed
- Invoke the right specialist for the domain being worked on (see Agent Routing tab)
- All work goes through a PR — no direct pushes to main under any circumstance
- Supervisor reviews every PR automatically and posts a comment with findings
CHANGES_REQUIRED— fix the flagged items and re-pushBLOCKED— PR cannot merge; resolve critical findings first
- Same agents available — same quality guidance locally
- All PRs go through the same supervisor review as engineers
- Cannot touch deploy files, CI workflows, Dockerfiles, or EC2 scripts — automatically blocked
- PRs touching more than 3 files without a linked task are flagged
- Use supervisor feedback as a learning tool — it cites the exact file and line number
When a founder completes a POC, the @elevate-master-orchestrator agent generates a structured spec file saved to .claude/specs/YYYY-MM-DD-<feature>.md. It captures the architectural decisions made, which agents were used, which patterns must be followed, and the exact constraints that cannot change. Engineers pick up this file — not a verbal brief — and build from a complete context. This is the single mechanism that eliminates duplicate POC cycles across the team.
.claude/specs/ — understand decisions before writing any code
[GKR], [UW], [Claims], [Infra], etc.
APPROVED
Invoke the right specialist for your domain. Using the wrong agent or a general-purpose prompt wastes tokens and produces less accurate results. The supervisor will flag if you re-implemented something an existing agent already handles.
| Agent | What it handles | Repo |
|---|---|---|
| @uw-specialist | Underwriting Hub, submission data, GKR agent responses, detail overlay tabs (Eligibility / Exposure / Loss / Completeness), mdToHtml rendering, submission_unified view | en-workspace |
| @claims-specialist | Claims Hub, WC FNOL pipeline, compensability assessment, reserve calculations, authority gates, wc_fnol_platform schema | en-workspace |
| @ba-specialist | Binding Authority portal, Great American + Century Surety carriers, 5 BA chunk types, producer eligibility workflows, BA chat and check endpoints | en-workspace |
| @psu-specialist | Public Sector Underwriting hub, county budget analysis, PSU submission data and risk intelligence | en-workspace |
| @renewal-specialist | Renewal portfolio queue, near-miss surface, cross-LOB signals, portfolio intelligence briefs | en-workspace |
| @audit-specialist | Compliance audit dashboard, three-way match display, override detection, variance analysis between AI verdicts and underwriter actions | en-workspace |
| @curation-specialist | GKR knowledge chunks, all 14 chunk types, ontology edges, chunk lifecycle (draft → active → expired), kcs_build CLI commands, two-layer content model | elevatenow-rule-layer |
| @pipeline-specialist | Conductor recipes, ToolChest deployment (flat layout rules), AGENT_RESPONSES key mapping, stale schema diagnosis, flask-server tool registration | elevatenow-rule-layer |
| @elevatenow-supervisor | Code review, security scan, architecture compliance check — invoke manually before a PR, or it runs automatically via CI on every PR | Both repos |
| @elevate-master-orchestrator | Multi-domain coordination, architecture decisions, POC-to-handoff spec generation. Use when a task spans more than one domain or requires cross-system reasoning | User-level |
If you are writing code that extracts fields from a document, checks insurance eligibility, assesses compensability, or resolves entities — check the routing table first. There is almost certainly an agent that already handles this. Re-implementing it is a waste of tokens and creates drift. The supervisor will flag it with the agent name you should have used.
The supervisor runs automatically via GitHub Actions on every pull request. It reads the full diff and checks 8 domains. Results are posted as a PR comment within seconds of opening the PR. No one needs to manually trigger it.
Hardcoded API keys, passwords, or connection strings in source code. SQL injection via f-strings. eval() or exec() on user input. .env file committed to git. Any finding here blocks the PR immediately.
LLM call outside platform_llm_client.py. Dockerfile running as root at runtime. AWS endpoints hardcoded. AGPL or GPL dependency added to requirements. Critical findings are blocked; others are changes-required.
TypeScript any without an explanatory comment. console.log in production files. Bare except: in Python. print() in production paths. TODO or FIXME comments in merged code.
VEN format instead of GKR format in agent responses. MongoDB write from a Workbench backend route. Tool calling elevatenow_gkr directly instead of interfaces/gkr_query.py. Nested folders inside Tool_Chest/Tools/. Input schema changed without re-registration.
Code re-implementing capabilities already owned by a fleet agent — document extraction, eligibility checking, compensability assessment, entity resolution, Conductor orchestration. The supervisor names the agent that should have been used.
LLM called inside a loop without batching. max_tokens not set on an LLM call. Passing entire files when only a diff is needed. LLM used for work that a regex or deterministic function can do reliably.
Commit message missing required [Prefix] type: description format. .DS_Store, *.pyc, or other generated files committed. Valid prefixes: [UW] [Claims] [BA] [GKR] [Tools] [Infra] [PSU] [Audit] [Workbench].
Deploy files modified (CI workflows, Dockerfiles, EC2 scripts, wrangler.toml). PR touches more than 3 files without a linked task reference. These findings are always blocked for freshers, changes-required for engineers.
Each finding includes the file path, line number, what the violation is, and a specific fix. Address the BLOCKED findings first — they are the only ones that prevent merge. CHANGES_REQUIRED items must be fixed before the next PR cycle but do not fail the build.
These rules are enforced by the supervisor on every PR. Understanding them before writing code prevents wasted cycles. The supervisor will cite the exact rule and the file that violated it.
- The Workbench backend (Express API at port 3001) only reads from MongoDB — it never writes
- All writes go through Conductor recipes executing on the workflow engine
- Writing directly from an Express route violates the data integrity model and will be blocked
- If you need to persist data, the correct path is through a Conductor workflow, not an API call
- All agent outputs must be:
{ response: "string", decision_trace: {} } - The old VEN format (
response.result+response.metadata) is completely banned — it will be blocked - Every decision must trace to a specific
chunk_id— the system is deterministic, not probabilistic - LLM agents are executors — the governed chunk is the authority, not the model's output
- All production tools live flat under
Tool_Chest/Tools/ClassName.pyonly - No subfolders inside
Tools/— the flask-server only loads from the flat directory - Files placed in nested folders are invisible to the server and create stale duplicates
- Dev-side folders (for local organization) are fine, but never commit nested structure to
Tools/
- The stored
input_schemaintool_database.toolsis the source of truth for validation — not the file - If a tool's input schema changes, the database record must be deleted and the tool re-registered in Agentic Studio
- Simply updating the Python file does nothing to the stored schema — the old validation will repeat identically
- Diagnostic: if the same error appears byte-for-byte on multiple runs, the stored schema is stale
- External tools must query GKR exclusively through
interfaces/gkr_query.py - Never query the
elevatenow_gkrMongoDB collection directly from a tool - The interface provides:
gate1(),gate2(),check_eligibility(),fnol_triage(),get_ontology_edges() - Direct database access bypasses governance and breaks the deterministic audit trail
- All LLM calls go through
CurationStudio/platform_llm_client.py— never a direct SDK call - The client handles Groq primary / OpenAI fallback automatically
- Temperature must be 0.0 for all extraction — deterministic decoding, never creative
- LLM is never used to generate facts: dollar amounts, dates, and codes are always regex-extracted
[Prefix] type: short descriptionExamples: [GKR] feat: add GL jurisdiction resolver chunk type · [UW] fix: strip STATUS_BLOCK from eligibility narrative · [Infra] feat: project-level agent fleet + supervisor CI
The fleet is not a set of optional tools. It is the engineering operating model for ElevateNow. These are the concrete outcomes it produces.
| Repository | Agents Installed | CI Secret |
|---|---|---|
vsrin/en-workspace |
uw-specialist, claims-specialist, ba-specialist, psu-specialist, renewal-specialist, audit-specialist, elevatenow-supervisor | GROQ_API_KEY ✓ |
vsrin/elevatenow-rule-layer |
curation-specialist, pipeline-specialist, elevatenow-supervisor | GROQ_API_KEY ✓ |
To add a new repo to the fleet: (1) create .claude/agents/ in the repo root, (2) copy the relevant specialist .md files from an existing repo, (3) add CLAUDE.md with the agent routing table, (4) copy .github/workflows/supervisor-review.yml and .github/scripts/run_supervisor.py, (5) add GROQ_API_KEY to the repo's GitHub Actions secrets. The GROQ key is already set — reuse it across all repos.