Skip to content

BluegReeno/hal

BranchesTags

Repository files navigation

hal

The second brain for field-work SMEs (BET, architects, surveyors).

hal is a BYOA (Bring Your Own AI) engine. It exposes one MCP server — hal-mcp, a Supabase Edge Function — that any Claude client (Claude Desktop, Claude Cowork, Claude Code, Dust, n8n) connects to. The agent runs client-side, on the caller's own Claude account; hal provides the data, the tools, and the memory.

It is a second brain because it holds, for a small firm, everything that usually lives in heads, email threads, and scattered files:

  • the pipeline — companies, contacts, projects, their stage and owner;
  • the work — tasks, sprints, deadlines, who does what;
  • the memory — logged interactions across the team;
  • the field — building inspections, photos, annotations, field notes (Edifice vertical);
  • the documents — KBIS, statuts, RIB, brand kit, fiscal records — facts extracted once, recalled forever (document vault).

The firm talks to it in natural language, from their own Claude, and it answers and acts — without a single line of glue code to maintain on their side.

hal is invisible to end-users. They see a commercial brand per vertical. Today there is one: Edifice (BET / building inspection).

hal is the AI-native company toolkit for SMEs. Where SaaS gives a small firm a screen to fill, hal gives the firm an agent that already knows its pipeline, tasks, field work, and documents — and acts from the chat the team already uses. The unit of value is the second brain, not the dashboard; the unit of distribution is the marketplace skill, not the install wizard.

Status: live in production. hal-mcp v0.2.1 deployed. 27 MCP tools across CRM, pipeline, tasks/sprints, document vault, identity, and the Edifice field workflow. CRM, vault, and the Edifice pull→push loop all run on Supabase zgkvbjqlvebttbnkklpo.

Source-of-truth docs: docs/prd.md (positioning, scope, roadmap), docs/architecture.md (cross-repo map).

Two-tier product model

┌─────────────────────────────────────────────────────────────────┐
│                          hal engine                             │
│        hal-mcp (Edge Function) · halcrm_* tables · vault         │
│         CRM · pipeline · tasks/sprints · document memory         │
└─────────────────────────────────────────────────────────────────┘
                              │
                              │ one flag per workspace
                              │
              ┌───────────────┴───────────────┐
              │    Edifice (BET vertical)      │
              │    edifice.enabled: true       │
              │    - edifice_* tools           │
              │    - Supabase edifice_* tables │
              │    - edifice-app field capture │
              │    - field-to-deliverable flow │
              └────────────────────────────────┘
Name Meaning
hal The generic second-brain engine — MCP server, CRM, tools, vault. Invisible to end-users.
Edifice Commercial brand for the BET vertical: structural consultancies, architects, surveyors, building diagnostics. What BET firms using the Edifice vertical see.
edifice-app Mobile PWA for on-site capture — lives at ../edifice/pwa/.
edifice-web Desktop webapp — lives at ../edifice/webapp/.

A workspace with edifice.enabled: false uses the generic core as a plain business second brain (the dogfood blue-green workspace). A workspace with edifice.enabled: true gains field capture, edifice_* read/write, and metier document generation. Future verticals (renewable energy diagnostics, etc.) will each get their own brand and module, all powered by the same engine.

How it works — BYOA + MCP

No server-side inference, no Python agent in the loop, no model lock. The caller's Claude client connects to hal-mcp over HTTP and reads with list_* tools, writes with the mutation tools. There is no fat-context injection: the agent pulls exactly the slice of the firm's brain it needs for the question at hand.

  Claude Desktop / Cowork / Code        Dust / n8n
  (OAuth, user JWT)                      (HAL_API_KEY)
            │                                  │
            └──────────────┬───────────────────┘
                           ▼  HTTP MCP
              ┌─────────────────────────────┐
              │   hal-mcp (Edge Function)    │
              │   Deno · @supabase/server    │
              │   verifyAuth user | secret   │
              └──────────────┬──────────────┘
                             ▼
              ┌─────────────────────────────┐
              │  Supabase zgkvbjqlvebttbnk…  │
              │  halcrm_* (RLS workspace)    │
              │  edifice_* · halcrm-vault    │
              └─────────────────────────────┘
  • Auth: verifyAuth({ auth: ["user", "secret"] }). Claude Cowork/Desktop authenticate with a Supabase user JWT (RLS enforced, scoped to workspace_members); Dust/n8n use the static HAL_API_KEY (service role, RLS bypassed) for server-to-server.
  • Isolation: every halcrm_* row carries a workspace_slug; RLS via workspace_members.
  • Distribution: the bluegreen-marketplace hal plugin bundles the connector (.mcp.json) and the skills, so installing the plugin wires the MCP server automatically.

MCP tools (hal-mcp v0.2.1)

27 tools. Reads are list_*/get_*; everything else mutates.

Identity

  • whoami — read-only probe: returns user_email, the user's workspaces[] (slug + role + is_default), and the server-resolved default_workspace_slug. Doubles as the connectivity check. User-mode only; secret-mode callers receive an error.

CRM

  • create_company · list_companies
  • create_contact · list_contacts
  • log_interaction — channel, summary, optional transcript + tags

Pipeline (projects)

  • list_stages — valid stages per kind (halcrm_workspaces.kind_stages)
  • list_projects — filter by stage/kind, summary_only to skip heavy descriptions
  • create_project · update_project (name, amount_ht, ref, location, due_date, …) · update_project_stage (sets closed_at on terminal stages)

Tasks & sprints

  • create_task · list_tasks · update_task (partial; no status, no sprint) · update_task_status (workspace_slug guard)
  • create_sprint · list_sprints (status filter — actuel resolves the current sprint) · update_sprint (rename, status, dates) · assign_task_to_sprint

Document vault

  • save_document — fiche + facts JSONB; returns a signed upload URL when a binary is attached
  • list_documents — summary_only gives per-domain counts + expiring_within_30d
  • get_document · get_document_file — signed download (TTL 300s for sensitive docs)

Edifice (conditional on edifice.enabled)

  • list_edifice_missions · read_edifice_mission
  • get_mission_with_assets — notes + annotations + photo signed URLs
  • push_mission_context — writes observations, building context, and optionally photos[] (crop_region + YOLO annotations); returns updated, photos_updated, annotations_upserted

Data model

All on Supabase project zgkvbjqlvebttbnkklpo.

halcrm_* — the firm's brain (workspace-isolated, RLS via workspace_members):

Table Holds
halcrm_workspaces one row per client firm — stages per kind, company_id, edifice flag, sprints_enabled
halcrm_companies / halcrm_contacts the CRM
halcrm_missions projects/opportunities (surfaced as "projects"; the SQL table name is historical) — stage, kind, amount, edifice link UUIDs
halcrm_tasks assignable work (assignee_user_id, status CHECK, optional external_ref loose-coupling pointer, optional priority)
halcrm_sprints IC sprint planning
halcrm_interactions logged touchpoints (call / email / meeting), optional transcript + tags
halcrm_documents the vault — domain validated per-workspace against allowed_tags, facts JSONB, valid_until, sensitive, binary in bucket halcrm-vault

edifice_* — buildings, projects, notes, photos, reports (source of truth: ../edifice/supabase/migrations/). Linked to halcrm_missions via two nullable UUID columns.

Migrations source of truth for halcrm_*: supabase/migrations/.

Surfaces

The firm reaches its second brain through whatever Claude client it already uses — same agent, same data, every time:

Surface Who How
Claude Desktop / Cowork Office team, power users hal-mcp via OAuth; hal plugin skills
Claude Code Renaud (dogfood), developers hal-mcp + /hal and /edifice skills
edifice-app (PWA) Field technicians Writes directly to Supabase edifice_*; read back by hal-mcp
Dust / n8n Automations hal-mcp via HAL_API_KEY

WhatsApp (one-liners from the road) is the intended near-term mobile surface — architecturally supported, not yet wired. Native iOS/Android apps are explicitly rejected.

Skills (bluegreen-marketplace, plugin hal v0.7.0)

  • /hal list [workspace] — text kanban of the pipeline by stage
  • /hal tasks [workspace] — current-sprint tasks across renaud + blue-green
  • /hal update <free text> — natural-language CRM writes (stage moves, interactions, new entities)
  • /hal devis [--workspace] — generate a DOCX devis (IC or Blue Green format) via scripts/generate_devis.py
  • /edifice pull → improve → report → push — the field-to-deliverable workflow (skill v0.3.1)

Skills (renaud-marketplace v0.4.0)

  • briefing (/briefing) v0.2.0 — morning briefing across hal (renaud + blue-green) + Obsidian jobsearch + the 3 Google Calendars
  • jobsearch v0.4.0 — cv-generator, log-application (job ad + source → Obsidian note + follow-up task), interview-prep (fixed structure, wired to the 5 CV profiles), and jobsearch-vault (filesystem-only vault I/O, shared library)

Field-to-deliverable method (Edifice)

Every Edifice engagement follows four phases — identical for a devis, a visite chantier report, or a diagnostic. Only the Phase-2 qualification logic differs.

flowchart TD
    A0([Client request]) --> A1["Phase 0 · Intake — office<br/>hal-mcp: project created, stage set, context logged"]
    A1 --> B1["Phase 1 · Field — edifice-app<br/>photos · annotations · measurements · voice notes → Supabase"]
    B1 --> C0["Phase 2 · Qualification — Cowork + Edifice skill<br/>get_mission_with_assets → qualify → push_mission_context"]
    C0 --> D1["Phase 3 · Report + Send — office<br/>DOCX render → edifice-reports → technician validates → sent"]
Loading
Type What qualification means
Devis Validate the need; identify unknowns before pricing (sondages, géotechnique, 3D model, load-bearing elements?)
Visite chantier For each annotation: does it raise a réserve (snag)?
Diagnostic Each annotation → building understanding, problem understanding, or a désordre with a condition index, root cause, and intervention modalities

Repository topology

Repo Role Source of truth for
github.com/BluegReeno/hal (this repo) Engine hal-mcp, halcrm_* migrations, vault, devis scripts, roadmap
github.com/bluegreen-ai/edifice (sibling) BET vertical edifice_* migrations, edifice-app PWA, edifice-web, report templates
bluegreen-marketplace Distribution hal plugin — /hal + /edifice skills, .mcp.json
auth-gateway Shared admin user invites, app_metadata, public.companies

Cross-repo changes → append to docs/cross-repo-log.md in the same commit. Full map: ../BLUEGREEN_MAP.md.

Repo layout

hal/
├── CLAUDE.md                      # Development guidelines
├── README.md                      # This file
│
├── supabase/
│   ├── functions/
│   │   ├── hal-mcp/index.ts       # THE runtime — 26 MCP tools
│   │   └── edifice-map-generator/ # IGN 2D map generation (pg_net trigger)
│   └── migrations/                # halcrm_* migrations (source of truth)
│
├── scripts/
│   ├── generate_devis.py          # /hal devis — docxtpl DOCX renderer (live)
│   ├── migrate_obsidian_to_supabase.py
│   └── sprint_transition.py
│
├── docs/
│   ├── prd.md                     # Product requirements (this product, current)
│   ├── architecture.md            # Cross-repo map + auth chain
│   ├── cross-repo-log.md          # hal ↔ edifice change log
│   ├── vault-seeding-blue-green.md# Vault seeding + accountant smoke-test runbook
│   ├── features/                  # Per-WP briefs (input to Archon)
│   └── workflow/                  # Archon playbook
│
└── hal/                           # Python support package for scripts/ (DOCX renderer, Supabase CRM DAO)

Legacy note: hal/ is a pre-BYOA remnant, trimmed to what scripts/ still needs — documents/ (the DOCX renderer behind /hal devis) and backends/crm_supabase.py / backends/edifice.py (the Supabase CRM DAO). The runtime is hal-mcp + Supabase. The retired VPS gateway, local-CLI agent, per-workspace config tree, and one-shot benchmark were removed in the Ops 1 purge (benchmark archived at git tag archive/benchmark-2026-06).

Develop & deploy

# Deploy the MCP server (the actual product)
supabase functions deploy hal-mcp        # project zgkvbjqlvebttbnkklpo

# Apply a halcrm_* migration — use the Supabase MCP apply_migration tool or the
# dashboard SQL editor. The Supabase CLI push is NOT safe on this shared
# partial-ledger DB; see docs/operations.md §1 for the runbook.

# Edge Function tests (Deno)
deno test supabase/functions/hal-mcp/

# Devis generation (Python)
uv run python scripts/generate_devis.py --workspace <workspace-slug> --json ctx.json

# Python tests (devis renderer, CRM DAO, migration tooling)
uv run pytest

Two Supabase accounts → per-directory auth via .envrc (direnv, SUPABASE_ACCESS_TOKEN). index.ts must end with export default { fetch: fetchHandler } (a deploy without it silently 404s — past incident, ~25 min down).

Required secrets (Supabase Edge Function)

  • HAL_API_KEY — static Bearer for server-to-server (Dust, n8n). Stored in Bitwarden. Reset: openssl rand -hex 32 + supabase secrets set + redeploy.
  • Supabase service + anon keys are injected by the platform.

Roadmap

Horizon Focus
Now Close the document vault WP — seed Blue Green (KBIS, statuts, RIB, CNI, brand kit) + the accountant smoke test. Run the Edifice pull→push E2E on a real mission.
Next Onboard BET clients with real missions. Daily dogfood loop on blue-green. Prune legacy Python + retire the hal-gateway VPS container.
Later WP3-B project-level cross-workspace sharing. WhatsApp channel (baileys multi-device). edifice-web kanban + chat sidebar.

Detailed ordering and rationale in docs/prd.md §7.

License

Proprietary — all rights reserved.

About

AI-native company layer for SMEs — CRM, tasks, document vault and field workflows via MCP (BYOA)

Topics

typescript mcp crm project-management document-management deno byoa edge-functions supabase ai-agent

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

1 tags

Packages

 
 
 

Contributors

Languages