ontologian

Ontologian

A Claude Code plugin for structured knowledge management based on Palantir Ontology concepts.

Ontologian brings Object Types, Link Types, and Action Types into your Claude Code workflow — letting you define, navigate, and validate your domain knowledge as structured YAML directly inside your project.

---

Installation

Step 1 — Register the marketplace

curl -fsSL https://raw.githubusercontent.com/swszz/ontologian/main/setup.sh | bash

Adds Ontologian's GitHub repo as a known marketplace source in ~/.claude/settings.json.

Requires: jq or python3.

Step 2 — Install commands & agent

Run inside Claude Code:

/plugin install ontologian@ontologian

Installs 9 slash commands (/ontologian, /ontologian:add, /ontologian:analyze, ...) and the ontology-consultant proactive agent.

Update

/plugin update ontologian@ontologian

No need to re-run setup.sh — this updates commands and agent only.

---

Commands

Command	Description
/ontologian:consult	Start a Palantir-grade ontology consulting session — guided discovery, design, construction, and governance documentation
/ontologian	Show domain list and status summary
/ontologian:add	Interactively add a new type to a domain
/ontologian:analyze	Derive ontology structure from free-form requirements
/ontologian:search <keyword>	Search across all domains (use --type object|link|action and --domain <name> to filter)
/ontologian:validate	Check YAML schema and referential integrity
/ontologian:sync	Sync local .ontology/ to the global store
/ontologian:migrate	Split a domain's single file into per-type files
/ontologian:visualize	Render an ASCII relationship diagram

Consulting Agent

The plugin includes an ontology-consultant agent that activates in two ways:

• Proactively — when you describe business requirements, system design, or domain entities, the agent automatically offers to model them as an ontology
• Explicitly — run /ontologian:consult to start a full consulting session immediately

The consulting session covers 6 phases:

Phase	What happens
Phase 0 — Scope	Confirm the domain scope and whether to start from existing requirements or a blank slate
Discovery	5-axis structured interview: entities, relationships, processes, boundaries, governance
Modeling	Autonomous candidate derivation using the same rules as /ontologian:analyze
Design	Palantir enrichment patterns: object enrichment, state machine audit, semantic naming review, governance metadata
Construction	Writes all domain files in dependency order, runs automatic validation
Delivery	Renders ASCII diagrams for all domains, generates .ontology/CONSULT_REPORT.md

---

Examples

/ontologian:consult
"We run a logistics platform. Shipments are assigned to Drivers, pass through Hubs, and each leg is tracked as a RouteSegment."

/ontologian:analyze
"Users sign up and place Orders. Each Order has multiple OrderItems linked to a Product. When an Order is confirmed, we send a confirmation email."

/ontologian:add
"Add a new Object Type called Invoice to the billing domain — has invoice_id, issued_at, total_amount, and status (draft, sent, paid, overdue)."

/ontologian:search order --type action
/ontologian:validate
/ontologian:visualize
/ontologian:sync

---

Plugin Structure

ontologian/
├── commands/
│   ├── ontologian.md            # /ontologian
│   └── ontologian/              # /ontologian:<name>
│       ├── add.md
│       ├── analyze.md
│       ├── consult.md
│       ├── migrate.md
│       ├── search.md
│       ├── sync.md
│       ├── validate.md
│       └── visualize.md
├── agents/
│   └── ontology-consultant.md   # Proactive consulting agent
├── hooks/
│   └── hooks.json
└── setup.sh                     # Marketplace registration script

commands/ is the single source of truth. Edit files there directly.

---

How It Works

The .ontology/ directory is created lazily — it does not exist until you run your first write command (/ontologian:add or /ontologian:analyze). Read-only commands (/ontologian, /ontologian:validate, /ontologian:search) require the directory to already exist.

When first created, the directory structure looks like this:

<project-root>/
└── .ontology/
    ├── config.yaml          # Plugin config (sync mode, global path)
    ├── domains/
    │   ├── _index.yaml      # Domain registry
    │   └── <domain-name>/
    │       └── ontology.yaml
    └── migrations/

Domain file structure

domain: ecommerce
version: 1
description: "E-commerce domain"