prathik10/pathways

Pathways

     

A conversational AI navigator for people leaving incarceration in Texas. Built as a Claude Code architecture: layered Skills, sub-agents, hooks, MCP servers, settings, and a distributable plugin, composed into one reliable workflow for a safety-critical domain.

This repo is both a real product-in-progress AND an opinionated demonstration of how Claude Code primitives compose when wrong answers cause real harm: legal misinformation, missed deadlines, lost benefits, or a missed crisis signal.

Status: Phase 7 complete (2026-05-18). The system runs end-to-end across three audiences (SMS user, PWA user, caseworker dashboard) on the same FastAPI + LangGraph + Skills + MCP backend. Phase 7 added a Leaflet + OpenStreetMap map view above the PWA resource cards (with Google Maps deep-link), per-turn map-engagement analytics on the dashboard, and a CI auto-deploy workflow that mirrors main to the HF Space on every merge. Quality signal: 305 unit tests + 73 eval scenarios all green; CI gates merges on a per-category pass rate with crisis at 100%. Two items remain deferred-with-design (`docs/PHASE6_DEFERRED.md`): MMS photo extraction and warm-transfer voice, both blocked by paid Twilio dependencies. The full chronological build is in `docs/JOURNAL.md`; an interview-prep tour through every layer is in `docs/INTERVIEW_BRIEFING.md`.

⚡ Try it in 30 seconds

Install as a Claude Code plugin (loads all 7 Skills + 4 sub-agents + 3 hooks into your own session)

git clone https://github.com/PrathikRavichandran/pathways.git
cd pathways && claude plugin install .

Then open any Claude Code session and ask a Texas-reentry question — the right Skill auto-loads, the safety hooks fire, the compliance-auditor sub-agent audits the response, and the MCP servers serve the corpus + resources. No model setup, no infra. The .claude/plugin.json manifest is the recruiter's quickest path to "this person actually shipped something I can install and run."

The problem this exists to solve

The first 72 hours after release are the highest-risk window for a returning citizen. Housing, ID documents, work authorization, parole reporting, mental health continuity, and benefits all collide in a narrow window — and the information that resolves them is fragmented across federal databases (NICCC), state agencies (TWC, HHSC), county courts, and local non-profits. Caseworkers spend most of their time looking things up rather than working with people.

Pathways is an SMS-first navigator (Twilio in prod, web for demo) that answers concrete questions — "can I get my driver's license back if my felony was a state jail felony from 2018?" — with cited answers, escalation gates, and a humane handoff to a real navigator when the model isn't certain.

Why this is a Claude Code project, not just a LangGraph app

The naive build is a LangGraph state machine with a few RAG tools. The reason that's not enough:

• —Deterministic guardrails belong outside the agent loop. Crisis-keyword detection cannot depend on the model deciding to be careful. It runs as a UserPromptSubmit hook.
• —Domain workflows shouldn't be inlined into a monolithic prompt. Each phase of a navigator's day — intake, eligibility check, resource matching, record-clearing eligibility, benefits navigation — is its own progressive-disclosure Skill, loaded only when relevant.
• —Specialized agents need narrowed capability, not broader. The compliance-auditor sub-agent is read-only and can only see retrieval outputs; the caseload-summarizer can read PostgreSQL views but cannot write back. Sub-agents here aren't about parallelism, they're about bounding what each part of the system can do.
• —External integrations want to be tools, not glue code. NICCC retrieval, Texas resource directories, and Twilio are MCP servers, so they're swappable and individually auditable.

The result: a system where every safety property is enforced at the right layer, and where every architectural choice has an explicit reason a human auditor can follow.

Architecture at a glance

                  ┌──────────────────────────────┐
   User (SMS) ───▶│  FastAPI ingress (Twilio webhook)  │
                  └──────────────┬───────────────┘
                                 │
                  ┌──────────────▼───────────────┐
                  │   UserPromptSubmit hook:      │  ◀── deterministic
                  │   crisis_keyword_check.py     │     (no model in path)
                  └──────────────┬───────────────┘
                                 │
                  ┌──────────────▼───────────────┐
                  │   LangGraph state machine     │
                  │   (pathways/graph.py)         │
                  │                               │
                  │   Claude Sonnet — routing &   │
                  │   synthesis. Haiku for        │
                  │   classification. Opus for    │
                  │   complex policy reasoning.   │
                  └────┬──────────────────────┬──┘
                       │                      │
        Skills auto-load by description       │
        ┌──────────────┼──────────────┐       │
        ▼              ▼              ▼       ▼
  intake-       niccc-         crisis-  record-clearing-tx
  assessment    lookup         response  benefits-navigator
                                          housing-pathway
                                          employment-pathway
                       │
        Sub-agents spawn for bounded work
        ┌──────────────┼──────────────┐
        ▼              ▼              ▼
  eligibility-   resource-     compliance-
  checker        matcher       auditor

                                 │
                       MCP servers (JSON-RPC)
        ┌──────────────┼──────────────┐
        ▼              ▼              ▼
  pathways-      tx-resources   twilio-sms
  corpus         (211 TX, TWC,  (sandbox in
  (NICCC RAG)     HUD, courts)  public repo)

  PostToolUse hook (rag_confidence_gate.py):
    blocks responses below confidence threshold,
    forces human-handoff phrasing.

  PreToolUse hook (pii_redact.py):
    redacts PII before any write to logs.

What each Claude Code primitive does in this repo, and why

This section is the one I'd want a screener to read carefully. The JD said "a short README explaining what each piece does and why you built it is more valuable than volume" — this is that.

Skills (.claude/skills/)

Seven Skills, each a single SKILL.md with progressive disclosure. Auto-loaded by description match.

Sub-agents (.claude/agents/)

Four sub-agents, each with narrowed permissions vs. the parent session — not broader.

Hooks (.claude/hooks/)

Three hooks. The pattern: hooks enforce safety properties that cannot depend on model judgment.

MCP servers (.mcp.json + mcp_servers/)

Two real, two stubbed. The two real ones run locally with seeded data so the repo runs end-to-end without external credentials.

Settings (.claude/settings.json)

The production posture in one file. Model tiering (Haiku for routing, Sonnet for synthesis, Opus reserved for complex policy reasoning), permission allow/deny lists scoping every write, allowManagedHooksOnly: true so the safety posture can't be silently relaxed.

CLAUDE.md

The operating constitution. Tight (under 80 lines). Always cite NICCC for legal claims. Never give legal advice. HITL gate on anything financial or legal. Texas-only scope.

Run it locally in 60 seconds

git clone https://github.com/PrathikRavichandran/pathways.git
cd pathways
cp .env.example .env        # no real keys needed for demo mode
uv venv && source .venv/bin/activate
uv pip install -r requirements.txt
claude                       # .claude/ auto-loads; .mcp.json connects local servers

Then in the Claude Code session:

I'm a 32yo just released from TDCJ Beto Unit two days ago. 2018 state jail
felony for possession. I need housing and I want to know if I can get my
license back.

You'll see: intake-assessment Skill auto-loads → routes to housing-pathway and record-clearing-tx → calls pathways-corpus and tx-resources MCP servers → compliance-auditor sub-agent validates citations → final response cites NICCC sections and offers SMS handoff to a real navigator.

What's shipped vs. deferred

What's next

The technical surface is comprehensive. What it needs now is real users and real feedback.

Operator-side wiring left to do (~half a day):

1. 1.Set PATHWAYS_ADMIN_TOKEN on the HF Space and add a daily GitHub Actions cron to POST to /admin/run-parole-reminders.
2. 2.Set HF_TOKEN (write-scope HF access token) as a repo secret so .github/workflows/deploy-hf.yml can push merges to the HF Space automatically; then gh workflow run deploy-hf.yml --ref main once to fire the first sync.
3. 3.Wire the forward phone map (pathways/sessions/phone_map.py with a small session_phones table; encrypt with PATHWAYS_PHONE_ENCRYPTION_KEY). Until this is in place, both parole reminders and NGO write-back persist in their queues and the daily cron reports skipped_no_phone honestly.
4. 4.Geocode the demo seed at mcp_servers/tx_resources/resources.json (one-line-per-entry lat/lon enrichment for the metro-Houston and metro-DFW rows) so the Phase 7 map view also renders against the seed catalog in pure-demo mode. Production already pins via the HRSA + curated metro ingest.

Then partner outreach. The dashboard exists so partner NGOs can see what's flowing through their region; that conversation is what unlocks pilot users.

Deferred-with-design. MMS extraction and warm-transfer voice are documented in `docs/PHASE6_DEFERRED.md` with their blockers and unblock criteria. Both gate on paid Twilio features.

Why I built this

A Claude Code architecture is most interesting when the cost of being wrong is high. Reentry is one of those domains. The same primitives — Skills for domain workflows, sub-agents for bounded capability, hooks for deterministic safety, MCP for swappable integration — apply directly to healthcare (where I do this professionally at MMI) and any other regulated context. This repo is the public, non-confidential expression of that architecture.

License

Apache 2.0. See LICENSE. The NICCC content excerpts seeded in mcp_servers/pathways_corpus/corpus.json are public-domain federal data.

Contact

Prathik Ravichandran — prathik.ravichandran.work@gmail.com — LinkedIn