TA Ops Agent

This is a trust-first recruiting ops operating system, packaged here as a public-safe repo for working on reliable AI operations over noisy enterprise data.

The system combines deterministic data extraction, LLM synthesis, trust gating, and role-scoped delivery to turn messy ATS workflows into actionable daily digests. The interesting part is not "AI for recruiting." The interesting part is how the repo separates what must be true in code from what can be synthesized by a model.

Why this repo is interesting

• Deterministic and probabilistic responsibilities are split on purpose.
• MCP integrations expose a large real-world API surface in a reusable way.
• Trust gates prevent low-confidence joins from driving live personalized delivery.
• The demo is public-safe and runs on sanitized fixtures with no secrets.
• Every major step is observable: snapshots, audits, digests, tests, and chart stubs.

Architecture

ATS MCP data -> deterministic snapshot -> attribution audit -> LLM synthesis
-> trust gates -> Slack digest / dashboard chart / operator review

Read more in docs/architecture.md and docs/evaluation-and-safety.md. For the canonical output identity and Slack-vs-dashboard-vs-role-report split, see docs/magellan-output-doctrine.md. For the current implementation checkpoint and shipped-vs-future-state status, see docs/current-state-checkpoint.md. For the future-state rebuild, see docs/magellan-v2-architecture.md. For phased implementation sequencing, see docs/magellan-v2-execution-roadmap.md. For the key unresolved architecture and product calls, see docs/magellan-v2-open-decisions-register.md. For the live pilot metric policy, see docs/pilot-metric-catalog.md. For the reviewed pilot operating procedure, see docs/pilot-service-runbook.md.

Current state

Today, Magellan already has:

• reviewed-release-driven Slack and dashboard delivery
• a Live-first product shell
• persona-specific operating surfaces
• weekly role progress reports as first-class release artifacts
• presentation-doctrine checks enforced in preflight

The biggest things that are still future-state are:

• the normalized V2 data core
• fully extracted identity / attribution / coordinator subsystems
• a persisted recruiter approve/send workflow for role reports
• a first-class operator console

See docs/current-state-checkpoint.md for the canonical checkpoint.

Public Demo

The public repo ships with a sanitized demo pack in demo/.

# start the local chart + demo server
./scripts/ta-demo-server

# inspect the latest sanitized snapshot
./scripts/ta-snapshot show

# generate a recruiter digest from fixture data
./scripts/ta-demo-digest --persona recruiter --dry-run

# generate a coordinator digest from fixture data
./scripts/ta-demo-digest --persona coordinator --date 2026-04-03 --dry-run

# run a fail-closed release preflight before preview or live sends
./scripts/ta-preflight --scope preview --personas recruiter,coordinator --skip-tests --skip-analytics

# build private live demo artifacts, then preview a live recruiter digest
./scripts/ta-snapshot live-build
./scripts/ta-demo-digest \
  --snapshot-dir "$PWD/reports/private/live-demo/snapshots" \
  --date 2026-04-02 \
  --recruiter avery-chen \
  --send-to-sam

Default demo URLs are served from http://127.0.0.1:4173.

What is included

• mcp/greenhouse/: Greenhouse Harvest v3 MCP server with retry logic and broad endpoint coverage
• mcp/slack/: Slack MCP server for DM delivery, allowlists, and Block Kit output
• lib/: structured snapshot contract, normalization, and digest data helpers
• demo/: sanitized fixtures, sample outputs, walkthrough, public demo server, and screenshots
• docs/: public architecture, evaluation, and framework notes
• scripts/: legacy ta-* commands retained for compatibility

Snapshot Contract

The public-facing data model is the Snapshot contract in lib/snapshot-schema.ts.

The stored demo fixtures include:

• recruiter_candidate_metrics
• recruiter_role_metrics
• coordinator_watchlist
• attribution_audit
• blocking_reasons
• allow_live_recruiter_digest
• allow_live_coordinator_digest
• synthesis

This is intentional: public fixtures should already be complete and trustworthy, not repaired at read time.

Evaluation and Safety

Magellan highlights the control surfaces that matter in production:

• bounded retry logic for external APIs
• snapshot validation before downstream use
• preview-only gates when attribution is incomplete
• separate treatment of candidate ownership, role support, and low-confidence activity signals
• explicit blocking reasons attached to delivery decisions

The repo includes automated checks for fixture completeness, trust gating, CLI behavior, and chart rendering.

Private Demo Workflow

For real demo data, Magellan writes local-only artifacts under reports/private/live-demo/:

• snapshots/snapshot-YYYY-MM-DD.json
• audits/people-map-YYYY-MM-DD.json
• audits/attribution-audit-YYYY-MM-DD.json
• audits/coordinator-validation-YYYY-MM-DD.json

That private build path is intentionally separate from the public demo/fixtures/ directory.

./scripts/ta-snapshot live-build
MAGELLAN_SNAPSHOT_DIR="$PWD/reports/private/live-demo/snapshots" ./scripts/ta-snapshot validate
MAGELLAN_SNAPSHOT_DIR="$PWD/reports/private/live-demo/snapshots" ./scripts/ta-snapshot audit

Slack preview sends work against allowlisted users. If the Slack app token lacks users:read.email, use --send-to-sam for preview or pass --recipient-slack-id for explicit live sends.

For recruiter/coordinator pilot sends, keep real Slack IDs in the ignored config/team.local.json overlay. A tracked template lives at config/team.local.example.json, and ./scripts/ta-recipient-audit --run-id RUN_ID shows trusted vs live-ready recipients plus any unmapped pilot users.

./scripts/ta-preflight is the canonical operator gate before release approval. It checks artifact availability, reviewed release state, read-only audits, persona gates, digest dry-runs, and optional test/build readiness, then exits non-zero if the requested scope is not safe.

MCP Packages

Greenhouse MCP

72 read-only tools plus a narrow gated write surface for application assignment and recruiter/coordinator hiring-team ownership repairs.

• Auth: OAuth2 client credentials with token caching
• Pagination: cursor-based
• Rate limiting: 429-aware bounded retry
• Write safety:
  • global kill-switch via ENABLE_GREENHOUSE_WRITE_OPS=true
  • required actor allowlist via GREENHOUSE_ALLOWED_WRITE_ACTOR_IDS
  • required human-readable audit reason
  • explicit confirmation flags and dry_run
  • no generic replace endpoint; only single-target repair tools
• Runtime: TypeScript, Node.js 18+

Slack MCP

6 tools for DM delivery, user lookup, and preview-safe message sending.

• Safety: DRY_RUN plus SLACK_ALLOWED_USERS
• Output: plain text or Block Kit
• Runtime: TypeScript, Node.js 18+

Public-Safety Notes

• Private operational reports and real company data are not tracked in this public repo.
• reports/ now documents the boundary between public demo fixtures and private live artifacts.
• config/team.json is a sanitized example configuration.
• The legacy ta-* command names remain for backward compatibility, but the public product name is Magellan.

License

MIT