{"id":45217020,"url":"https://github.com/flyingrobots/xyph","last_synced_at":"2026-02-20T17:13:12.027Z","repository":{"id":338714623,"uuid":"1158831368","full_name":"flyingrobots/xyph","owner":"flyingrobots","description":"The Causal Operating System for Agentic Orchestration","archived":false,"fork":false,"pushed_at":"2026-02-16T02:30:58.000Z","size":472,"stargazers_count":0,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-16T08:46:27.970Z","etag":null,"topics":["agentic-os","ai","causal-ai","warp-graphs"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flyingrobots.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-16T01:00:23.000Z","updated_at":"2026-02-16T01:17:20.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/flyingrobots/xyph","commit_stats":null,"previous_names":["flyingrobots/xyph"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/flyingrobots/xyph","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyingrobots%2Fxyph","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyingrobots%2Fxyph/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyingrobots%2Fxyph/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyingrobots%2Fxyph/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flyingrobots","download_url":"https://codeload.github.com/flyingrobots/xyph/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyingrobots%2Fxyph/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29658176,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-20T16:33:43.953Z","status":"ssl_error","status_checked_at":"2026-02-20T16:33:43.598Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-os","ai","causal-ai","warp-graphs"],"created_at":"2026-02-20T17:13:11.912Z","updated_at":"2026-02-20T17:13:12.022Z","avatar_url":"https://github.com/flyingrobots.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"```text\n                                                              ██████\n                                                              ██████\n   ████████  ███████████████    ███████ ██████  █████████     ██████  ██████\n     ██████ ███████   ██████    ██████  █████  ████   █████   █████ █████████\n      █████ █████      ██████  ██████   ████ ████     ██████  ████  █  ███████\n        ████████       ██████ ██████    ████ ███     ███████  ████ █   ███████\n      ███████████       █████ █████     ████████    ███████   ██████   ███████\n     ██████ ███████      ██████████     ██████████████████    ██████   ███████\n   ████████  ███████      ████████      ██████ ██████████     ██████   ███████\n                           ██████       ██████\n                          ██████        ██████\n                         ██████         ██████\n```\n\n# XYPH ([/ˌzɪf/](https://ipa-reader.com/?text=%CB%8Cz%C9%AAf))\n**The Causal Operating System for Agentic Orchestration**\n\nXYPH is a planning compiler where the project roadmap is a living, deterministic graph. Humans and agents collaborate by reading and writing to that graph — no server, no database, just git.\n\n## How It Works\n\nEverything lives in a single **WARP graph** — a multi-writer CRDT stored in git. Humans decide *what* to build and *why*. Agents figure out *how* and do the work. Nobody sends messages to coordinate; instead, everyone reads and writes to the shared graph. This pattern is called **stigmergy** — coordination through the environment itself.\n\nThe rest of this README tells that story through a walkthrough. Ada is a human. Hal is an agent. They're going to build a feature together.\n\n## Getting Started\n\n**Prerequisites:** Node.js v20+, Git\n\n```bash\nnpm install\n```\n\nEvery participant has an identity set via the `XYPH_AGENT_ID` environment variable. Humans use the `human.` prefix; agents use `agent.`:\n\n```bash\nexport XYPH_AGENT_ID=human.ada    # Ada is a human\nexport XYPH_AGENT_ID=agent.hal    # Hal is an agent\n```\n\nVerify everything is working:\n\n```bash\nnpx tsx xyph-actuator.ts status --view roadmap\n```\n\n## Walkthrough: Building a Feature Together\n\n### 1. Ada Declares an Intent\n\nEvery piece of work in XYPH must trace back to a human decision. Ada starts by declaring an **Intent** — a statement of *why* something should exist. Intents are the sovereign roots of all work; agents cannot create them.\n\n```bash\nexport XYPH_AGENT_ID=human.ada\n\nnpx tsx xyph-actuator.ts intent intent:live-alerts \\\n  --title \"Users need real-time notifications\" \\\n  --requested-by human.ada\n```\n\nThis creates an `intent:` node in the graph. Everything built downstream will point back here.\n\n### 2. Ada Plans the Work\n\nAda groups related work under a **Campaign** — a named collection, like a milestone or epic. Inside the campaign she creates **Quests** — the individual units of work (think tickets or tasks). Each quest belongs to a campaign and is authorized by an intent:\n\n```bash\nnpx tsx xyph-actuator.ts quest task:notif-001 \\\n  --title \"WebSocket event bus\" \\\n  --campaign campaign:live-alerts \\\n  --intent intent:live-alerts\n\nnpx tsx xyph-actuator.ts quest task:notif-002 \\\n  --title \"Toast notification UI\" \\\n  --campaign campaign:live-alerts \\\n  --intent intent:live-alerts\n```\n\nThe chain from quest → campaign → intent is the **Genealogy of Intent**. It's how XYPH enforces that every piece of work traces back to a human decision (Constitution Art. IV).\n\nAda can also toss a rough idea into the **Inbox** for triage later:\n\n```bash\nnpx tsx xyph-actuator.ts inbox task:notif-003 \\\n  --title \"Maybe: email digest fallback?\" \\\n  --suggested-by human.ada\n```\n\nAnd later promote or reject it:\n\n```bash\nnpx tsx xyph-actuator.ts promote task:notif-003 --intent intent:live-alerts\nnpx tsx xyph-actuator.ts reject task:notif-003 --rationale \"Out of scope for v1\"\n```\n\n### 3. Hal Sets Up\n\nHal is a **Causal Agent** — an autonomous participant with its own writer identity in the graph. Before doing any work, Hal generates a cryptographic keypair (one-time setup):\n\n```bash\nexport XYPH_AGENT_ID=agent.hal\n\nnpx tsx xyph-actuator.ts generate-key\n```\n\nThis creates an Ed25519 private key in `trust/agent.hal.sk` (gitignored) and registers the public key. Hal's completed work will carry a verifiable **Guild Seal** — a cryptographic signature proving who did the work.\n\n### 4. Hal Claims a Quest\n\nHal checks the roadmap for available work:\n\n```bash\nnpx tsx xyph-actuator.ts status --view roadmap\n```\n\nHe sees `task:notif-001` in BACKLOG and volunteers for it using the **Optimistic Claiming Protocol (OCP)** — a pattern where agents claim work optimistically and the graph resolves conflicts via CRDT convergence:\n\n```bash\nnpx tsx xyph-actuator.ts claim task:notif-001\n```\n\nIf two agents claim the same quest simultaneously, last-writer-wins. No locks, no race conditions — just deterministic resolution.\n\n### 5. Hal Does the Work\n\nHal creates a feature branch, implements the WebSocket event bus, and passes quality gates:\n\n```bash\nnpm run build \u0026\u0026 npm test\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for the full development workflow.\n\n### 6. Hal Seals the Quest\n\nWhen the work is done, Hal **seals** the quest. This marks it DONE and produces a **Scroll** — a cryptographic artifact that records *what* was built, *who* built it, and *why* it was authorized:\n\n```bash\nnpx tsx xyph-actuator.ts seal task:notif-001 \\\n  --artifact abc123def456 \\\n  --rationale \"WebSocket bus implemented and tested\"\n```\n\nThe scroll is signed with Hal's Guild Seal and linked to the quest in the graph.\n\n### 7. Ada Checks the Result\n\nAda opens the dashboard to see the full picture:\n\n```bash\nXYPH_AGENT_ID=human.ada ./xyph-dashboard.tsx\n```\n\nShe can see the campaign, its quests, who claimed them, and the sealed scrolls — all traceable back to her original intent. The lineage view (`status --view lineage`) shows the complete Genealogy of Intent from scroll → quest → campaign → intent → human.\n\nShe can also audit that every quest has a valid chain:\n\n```bash\nnpx tsx xyph-actuator.ts audit-sovereignty\n```\n\n## Dashboard\n\nThe interactive TUI provides a visual browser for the WARP graph:\n\n```bash\nXYPH_AGENT_ID=human.yourname ./xyph-dashboard.tsx\n```\n\n| Key     | Action                                        |\n|---------|-----------------------------------------------|\n| `Tab`   | Cycle views (roadmap → lineage → all → inbox) |\n| `↑↓`   | Navigate                                      |\n| `Space` | Fold/unfold campaign · open quest detail      |\n| `r`     | Refresh snapshot                              |\n| `?`     | Help modal                                    |\n| `p`     | Promote inbox task (human.* only)             |\n| `x`     | Reject inbox task                             |\n| `Esc`   | Close modal                                   |\n| `q`     | Quit                                          |\n\n## CLI Reference\n\nAll commands run via `npx tsx xyph-actuator.ts \u003ccommand\u003e`.\n\n| Command | What it does |\n|---------|-------------|\n| `status --view \u003croadmap\\|lineage\\|all\\|inbox\u003e` | View the graph (`--include-graveyard` to see rejected) |\n| `intent \u003cid\u003e --title \"...\" --requested-by human.\u003cname\u003e` | Declare a sovereign intent |\n| `quest \u003cid\u003e --title \"...\" --campaign \u003cid\u003e --intent \u003cid\u003e` | Create a quest |\n| `inbox \u003cid\u003e --title \"...\" --suggested-by \u003cprincipal\u003e` | Suggest a task for triage |\n| `promote \u003cid\u003e --intent \u003cid\u003e` | Promote inbox task to backlog |\n| `reject \u003cid\u003e --rationale \"...\"` | Reject to graveyard |\n| `reopen \u003cid\u003e` | Reopen a rejected task |\n| `claim \u003cid\u003e` | Volunteer for a quest (OCP) |\n| `seal \u003cid\u003e --artifact \u003chash\u003e --rationale \"...\"` | Mark done; produces a guild-sealed scroll |\n| `generate-key` | Generate an Ed25519 Guild Seal keypair |\n| `audit-sovereignty` | Verify all quests have a Genealogy of Intent |\n\n## Architecture\n\n```text\nsrc/\n├── domain/           # Pure domain models (Quest, Intent, ApprovalGate, ...)\n├── ports/            # Interfaces (RoadmapPort, DashboardPort, IntakePort, ...)\n├── infrastructure/\n│   └── adapters/     # git-warp adapters (WarpRoadmapAdapter, WarpDashboardAdapter, ...)\n└── tui/              # Ink-based interactive dashboard\n    ├── Dashboard.tsx         # Root component (landing, help, tab routing)\n    ├── HelpModal.tsx         # ? key help overlay\n    ├── QuestDetailPanel.tsx  # Reusable quest detail panel\n    ├── Scrollbar.tsx\n    ├── logos/                # ASCII art logos (1–10.txt)\n    └── views/\n        ├── LandingView.tsx   # Startup screen with WARP stats\n        ├── RoadmapView.tsx   # Campaign/quest tree with fold/unfold\n        ├── LineageView.tsx   # Genealogy of Intent tree\n        ├── AllNodesView.tsx  # Full graph node browser\n        └── InboxView.tsx     # Triage inbox (Gmail-style)\n\n# Root entry points\nxyph-actuator.ts    # CLI for graph mutations (quest, intent, seal, ...)\nxyph-dashboard.tsx  # Interactive TUI entry point\n```\n\n## Milestones\n\n| # | Milestone | Status |\n|---|-----------|--------|\n| 1 | BEDROCK — foundations, repo, actuator | ✅ DONE |\n| 2 | HEARTBEAT — coordinator daemon + ingest pipeline | ✅ DONE |\n| 3 | TRIAGE — rebalancer + origin context | ✅ DONE |\n| 4 | SOVEREIGNTY — cryptographic guild seals, approval gates, genealogy of intent | ✅ DONE |\n| 4+ | POWERLEVEL™ — full orchestration pipeline refactor | ✅ DONE |\n| 5 | WARP Dashboard TUI — interactive graph browser | 🚧 IN PROGRESS |\n| 6 | WEAVER — DAG scheduling + dependency graph ([RFC_001](docs/canonical/RFC_001_AST_DRIVEN_INGEST.md)) | ⬜ PLANNED |\n| 7 | ORACLE — intent classification + policy engine | ⬜ PLANNED |\n| 8 | FORGE — emit + apply phases | ⬜ PLANNED |\n\n## Constitution\n\nEvery mutation must obey the [CONSTITUTION.md](docs/canonical/CONSTITUTION.md). Key articles:\n\n- **Art. II** — No cycles in the dependency graph (hard reject)\n- **Art. IV** — Every quest must have a Genealogy of Intent (sovereign `intent:` root)\n- **Art. IV.2** — Critical path changes require an ApprovalGate signed by a human\n\n### Canonical Docs\n\nThe `docs/canonical/` directory contains the foundational specifications:\n\n- [ARCHITECTURE.md](docs/canonical/ARCHITECTURE.md) — System architecture\n- [GRAPH_SCHEMA.md](docs/canonical/GRAPH_SCHEMA.md) — Node and edge type definitions\n- [ORCHESTRATION_SPEC.md](docs/canonical/ORCHESTRATION_SPEC.md) — Planning pipeline phases\n- [SECURITY_AND_TRUST.md](docs/canonical/SECURITY_AND_TRUST.md) — Cryptographic trust model\n- [VISION_NORTH_STAR.md](docs/canonical/VISION_NORTH_STAR.md) — Project vision\n\n---\n\nBuilt with Ω¹ by [FLYING ROBOTS](https://github.com/flyingrobots)\n\n\u003csub\u003e¹ Ω (Omega) — the final convergence point of the WARP graph; symbolizes deterministic state resolution.\u003c/sub\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflyingrobots%2Fxyph","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflyingrobots%2Fxyph","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflyingrobots%2Fxyph/lists"}