diff --git a/README.md b/README.md index 25c40c9..f74fb6a 100644 --- a/README.md +++ b/README.md @@ -1,207 +1,140 @@ # oddkit -Agent-first CLI for ODD-governed repos. Portable Librarian + Validation with baseline knowledge. +An open-source MCP server that gives your AI structured memory, epistemic discipline, and the ability to build on what came before. -> **Authoritative:** [docs/oddkit/CHARTER.md](docs/oddkit/CHARTER.md) -> -> OddKit is epistemic terrain rendering (map), not epistemic authority (compass). +> **Your AI forgets everything between sessions. It guesses instead of checking. It can't tell a brainstorm from a decision. oddkit fixes that.** -## Deployment Methods +oddkit reads markdown files from a GitHub repository — decisions, constraints, learnings, governance — and makes them available to your AI through structured tools. It works with any AI tool that supports MCP: Claude, ChatGPT, Gemini, Cursor, Claude Code, Lovable, Replit, ElevenLabs voice agents, and more. -oddkit runs in three ways: +**Knowledge base repo:** [klappy/klappy.dev](https://github.com/klappy/klappy.dev) — the content oddkit reads from -| Method | Use Case | Setup | -| ---------------- | ---------------------- | ------------------------------------------- | -| **CLI** | Terminal usage | `npx oddkit ` | -| **MCP (local)** | Cursor, Claude Code | `npx oddkit init --claude` | -| **MCP (remote)** | Claude.ai iOS/iPad/web | Auto-deploys via Cloudflare Git integration | - -### Production Deployment +--- -The Cloudflare Worker deploys automatically via Git integration: +## Get Started in 30 Seconds -- **`main`** branch → staging preview deploy (auto-generated URL) -- **`prod`** branch → production (`oddkit.klappy.dev`) +oddkit is a remote MCP server. You don't install anything — you point your AI tool at a URL. -To promote staging to production: `./scripts/promote.sh` +### Claude.ai -See [workers/README.md](workers/README.md) for full deployment details. +Settings → Connectors → Add Custom Integration: +- **Name:** `oddkit` +- **URL:** `https://oddkit.klappy.dev/mcp` -## Documentation +### ChatGPT -| Doc | What It Covers | -| ----------------------------------------------------------------- | ------------------------------- | -| [**System Overview**](docs/getting-started/odd-agents-and-mcp.md) | How all the pieces fit together | -| [**Agents Guide**](docs/getting-started/agents.md) | Set up Epistemic Guide + Scribe | -| [**Ledger Guide**](docs/getting-started/ledger.md) | Learnings and decisions capture | -| [**QUICKSTART**](docs/QUICKSTART.md) | CLI and MCP setup in 60 seconds | -| [**MCP Reference**](docs/MCP.md) | Full MCP integration details | +Settings → Developer Mode → Create App → add MCP server URL: -## Quick Start +`https://oddkit.klappy.dev/mcp` -```bash -# Install dependencies -npm install +### Claude Code / Cursor / Any MCP Client -# Build index (optional, auto-builds on first query) -oddkit index +Add to your `.mcp.json`: -# Ask a policy question -oddkit librarian --query "What is the definition of done?" - -# Validate a completion claim -oddkit validate --message "Done with the UI update. Screenshot: ui.png" - -# Explain the last result in human-readable format -oddkit explain --last +```json +{ + "mcpServers": { + "oddkit": { + "type": "http", + "url": "https://oddkit.klappy.dev/mcp" + } + } +} ``` -## Commands +Or in Claude Code: `claude mcp add --transport http oddkit https://oddkit.klappy.dev/mcp` -### `oddkit index` +### Lovable / Replit / Gemini / ElevenLabs / Others -Build or rebuild the document index. +Any tool that supports MCP can connect. Look for "MCP server" or "custom integration" in your tool's settings and provide the URL: -```bash -oddkit index --repo /path/to/repo -``` +`https://oddkit.klappy.dev/mcp` -### `oddkit librarian` +--- -Ask a policy or lookup question. Returns citations with quotes. +## What oddkit Does -```bash -oddkit librarian --query "What is the rule about visual proof?" --format json -``` +Once connected, your AI gets access to these tools: -Options: +| Tool | What It Does | +|------|-------------| +| **orient** | Assess a situation, surface unresolved questions, identify which mode you're in (exploring, planning, executing) | +| **search** | Find relevant documents, constraints, and prior decisions by topic | +| **get** | Fetch a specific document by URI | +| **challenge** | Pressure-test a claim, assumption, or proposal against existing constraints | +| **gate** | Check readiness before transitioning between phases | +| **encode** | Structure a decision, insight, or boundary as a durable record | +| **preflight** | Pre-implementation check — surfaces constraints, definition of done, and pitfalls | +| **validate** | Verify completion claims against required artifacts | +| **catalog** | List available documentation with filtering and sorting | -- `-q, --query ` — The question to ask (required) -- `-r, --repo ` — Repository root (default: current directory) -- `-f, --format ` — Output format: `json` or `md` (default: `json`) +### Try It Right Now -### `oddkit validate` +After connecting, try these prompts: -Validate a completion claim. Returns verdict + evidence gaps. +- *"Orient me on [your current project challenge]"* +- *"Challenge the assumption that [something you believe]"* +- *"Search for any decisions about [a topic]"* +- *"Encode this decision: we chose X because Y"* -```bash -oddkit validate --message "Shipped the new feature" --format json -``` +--- + +## Bootstrap Your Project -Options: +To make oddkit proactive — so the AI uses these tools automatically instead of waiting for you to ask — add a bootstrap prompt to your project instructions. See the [full bootstrap guide](https://klappy.dev/page/docs/oddkit/proactive/proactive-bootstrap) or start with the essentials in [Getting Started with ODD and oddkit](https://klappy.dev/page/writings/getting-started-with-odd-and-oddkit). -- `-m, --message ` — The completion claim (required) -- `-r, --repo ` — Repository root (default: current directory) -- `-a, --artifacts ` — Optional JSON file with additional artifacts -- `-f, --format ` — Output format: `json` or `md` (default: `json`) +--- -### `oddkit explain` +## Point oddkit at Your Own Knowledge Base -Explain the last oddkit result in human-readable format. +By default, oddkit reads from [klappy.dev](https://github.com/klappy/klappy.dev). You can point it at any GitHub repo using the `canon_url` parameter: -```bash -oddkit explain --last -oddkit explain --last --format json +``` +canon_url: "https://raw.githubusercontent.com/YOUR_ORG/YOUR_REPO/main" ``` -Options: - -- `--last` — Explain the last result (default: true) -- `-f, --format ` — Output format: `md` or `json` (default: `md`) +oddkit reads markdown files with YAML frontmatter. Start with a few files — decisions, constraints, learnings — and grow from there. No schema required. -The explain command: +--- -- Shows what happened (status/verdict) -- Explains why it happened (which rules fired) -- Suggests what to do next -- Lists evidence used (citations, origin) -- Includes debug info (baseline ref, timestamp) +## Architecture -## Baseline Knowledge +oddkit is a Cloudflare Worker that: -By default, oddkit loads the [klappy.dev](https://github.com/klappy/klappy.dev) repo as baseline knowledge. +1. Fetches markdown files from a GitHub repository (zip download, cached) +2. Indexes them with BM25 full-text search +3. Parses YAML frontmatter for metadata, filtering, and sorting +4. Exposes structured tools via the MCP protocol -### Resolution Order +It's stateless, serverless, and framework-agnostic. The knowledge base is your repo. oddkit just makes it searchable and structured. -1. `--baseline ` CLI flag (highest priority) -2. `ODDKIT_BASELINE` environment variable (path or git URL) -3. Default: `https://github.com/klappy/klappy.dev` +--- -### Configuration +## Development ```bash -# Override baseline via CLI flag -oddkit librarian -q "What is done?" --baseline /path/to/local/canon -oddkit librarian -q "What is done?" --baseline https://github.com/yourorg/your-canon.git - -# Override baseline via environment variable -export ODDKIT_BASELINE="https://github.com/yourorg/your-canon.git" -oddkit librarian -q "What is done?" - -# Pin to a specific branch/tag -export ODDKIT_BASELINE_REF="v1.0.0" -oddkit librarian -q "What is done?" +cd workers +npm install +npm run dev # Local development +npm run deploy # Deploy to Cloudflare ``` -### Cache Location - -- Git repos are cloned to `~/.oddkit/cache///` -- Local paths are used directly (no caching) -- Local docs can override baseline via `supersedes` frontmatter field +**Branches:** +- `main` → staging preview +- `prod` → production (`oddkit.klappy.dev`) -## Supersedes Override +Promote staging to production: `./scripts/promote.sh` -A local doc can override a baseline doc by declaring: - -```yaml ---- -supersedes: klappy://canon/definition-of-done --- -``` -The baseline doc with that URI will be suppressed from results. +## Learn More -## Output Format +- **[Getting Started with ODD and oddkit](https://klappy.dev/page/writings/getting-started-with-odd-and-oddkit)** — five-minute quickstart with bootstrap instructions +- **[The Journey from AI Tasks to AI-Augmented Workflows](https://klappy.dev/page/writings/the-journey-from-ai-tasks-to-ai-augmented-workflows)** — the four-step progression +- **[From Passive to Proactive](https://klappy.dev/page/writings/from-passive-to-proactive)** — the story behind oddkit's proactive design +- **[klappy.dev repo](https://github.com/klappy/klappy.dev)** — the knowledge base oddkit reads from -### Librarian JSON - -```json -{ - "status": "SUPPORTED", - "answer": "Found 3 relevant document(s)...", - "evidence": [ - { - "quote": "MUST provide visual proof...", - "citation": "canon/visual-proof.md#Operating Constraints", - "origin": "baseline" - } - ], - "read_next": [{ "path": "canon/definition-of-done.md#DoD", "reason": "Primary source" }] -} -``` - -### Validate JSON - -```json -{ - "verdict": "NEEDS_ARTIFACTS", - "claims": ["Done with the UI update"], - "required_evidence": ["screenshot", "visual artifact"], - "provided_artifacts": [], - "gaps": ["screenshot", "visual artifact"] -} -``` - -## For Agents - -This CLI is designed to be called by AI agents: - -```bash -# Agent asks a question -oddkit librarian -q "What evidence is required for UI changes?" -f json +--- -# Agent validates completion -oddkit validate -m "Implemented search with autocomplete. Screenshot: search.png" -f json -``` +## License -JSON output is canonical and machine-parseable. +MIT