{
  "id": "page:docs-development-01-overview-and-philosophy",
  "_kind": "Page",
  "_file": "wiki/docs/development/01-overview-and-philosophy.md",
  "_cluster": "wiki",
  "attributes": {
    "nodeKind": "Page",
    "sourcePath": "docs/development/01-overview-and-philosophy.md",
    "sourceKind": "repo-docs",
    "title": "a5c: Overview & Development Philosophy",
    "displayName": "a5c: Overview & Development Philosophy",
    "slug": "docs/development/01-overview-and-philosophy",
    "articlePath": "wiki/docs/development/01-overview-and-philosophy.md",
    "article": "\n# a5c: Overview & Development Philosophy\n\n## What is a5c?\n\na5c is an agent orchestration platform that enables any coding agent (Claude Code, Codex, Pi, Gemini CLI, Copilot CLI, etc.) to execute structured processes — from simple CI tasks to complex multi-phase development workflows. It unifies the fragmented landscape of coding agents behind a single launch, orchestration, and observability surface.\n\n## Core Principle: Ontology-Driven Development\n\nThe platform is built on a knowledge graph (atlas) that models every agent, capability, provider, transport, hook surface, and plugin target as interconnected nodes with typed edges. Development decisions are driven by the graph, not by hardcoded if/else chains:\n\n```mermaid\ngraph TB\n    subgraph \"Knowledge Layer\"\n        ATLAS[\"Atlas Graph<br/>(YAML → JSON index)\"]\n        CATALOG[\"Agent Catalog<br/>(query API)\"]\n    end\n\n    subgraph \"Evidence Layer\"\n        SOURCES[\"Source Evidence<br/>(docs, changelogs, APIs)\"]\n        EXPERIMENTS[\"Experimental Evidence<br/>(live-stack E2E tests)\"]\n    end\n\n    subgraph \"Runtime Layer\"\n        ADAPTERS[\"Adapters<br/>(thin wrappers, data from graph)\"]\n        LAUNCH[\"Launch<br/>(adapters launch)\"]\n        PROXY[\"Proxy<br/>(transport-adapter)\"]\n        HOOKS[\"Hooks<br/>(hooks-adapter)\"]\n    end\n\n    SOURCES --> ATLAS\n    EXPERIMENTS --> ATLAS\n    ATLAS --> CATALOG\n    CATALOG --> ADAPTERS\n    CATALOG --> LAUNCH\n    CATALOG --> PROXY\n    CATALOG --> HOOKS\n```\n\n### Evidence Types\n\nEvery capability claim in the graph is backed by evidence:\n\n| Evidence Type | Source | Example |\n|---------------|--------|---------|\n| **Source** | Documentation, changelogs, API specs | \"Claude Code supports MCP\" → link to docs |\n| **Experimental** | Live-stack E2E tests | \"Claude Code + Foundry proxy works\" → CI run artifacts |\n| **Inferred** | Derived from other evidence | \"If supports MCP, likely supports tool use\" |\n| **Gap** | Known missing evidence | \"Pi hook support — no docs found\" |\n\n### How the Graph Drives Code\n\nInstead of each adapter hardcoding its capabilities:\n\n```typescript\n// OLD: hardcoded in adapter\nreadonly capabilities = { canResume: true, supportsMCP: true, ... };\n\n// NEW: derived from graph\nget capabilities() {\n  const flags = getCapabilityFlags(this.agent);\n  return { canResume: Boolean(flags.canResume), ... };\n}\n```\n\nAdding a new harness means adding a YAML file to the atlas graph — not writing adapter code for every capability.\n\n## Architecture Overview\n\n```mermaid\ngraph TB\n    subgraph \"User / CI\"\n        DEV[\"Developer\"]\n        CI[\"GitHub Actions\"]\n    end\n\n    subgraph \"Entry Points\"\n        ADAPTERS[\"adapters CLI<br/>(adapters)\"]\n        TRIGGERS[\"Triggers<br/>(GitHub Action)\"]\n        KRADLE[\"Kradle<br/>(Kubernetes operator + web UI)\"]\n    end\n\n    subgraph \"Orchestration\"\n        SDK[\"Babysitter SDK<br/>(run lifecycle)\"]\n        HOOKS[\"Hooks-Adapter<br/>(lifecycle normalization)\"]\n    end\n\n    subgraph \"Transport\"\n        PROXY[\"Transport-Adapter<br/>(protocol bridge)\"]\n        ENGINES[\"Completion Engines<br/>(OpenAI, Google)\"]\n    end\n\n    subgraph \"Knowledge\"\n        ATLAS[\"Atlas Graph\"]\n        CATALOG[\"Agent Catalog\"]\n    end\n\n    subgraph \"Agents\"\n        CC[\"Claude Code\"]\n        CX[\"Codex\"]\n        PI[\"Pi\"]\n        GC[\"Gemini CLI\"]\n        MORE[\"...8 more\"]\n    end\n\n    DEV --> ADAPTERS\n    CI --> TRIGGERS\n    TRIGGERS --> ADAPTERS\n    KRADLE --> ADAPTERS\n\n    ADAPTERS --> CATALOG\n    ADAPTERS --> PROXY\n    ADAPTERS --> CC & CX & PI & GC & MORE\n\n    CC & CX & PI --> HOOKS\n    HOOKS --> SDK\n    CC & CX & PI --> PROXY\n    PROXY --> ENGINES\n\n    CATALOG --> ATLAS\n```\n\n## Package Map\n\n| Package | Role |\n|---------|------|\n| `packages/atlas` | Knowledge graph: YAML definitions → JSON index |\n| `@a5c-ai/atlas/catalog` | Query API over the atlas graph |\n| `packages/adapters/cli` | `adapters` CLI: launch, install, run |\n| `packages/adapters/adapters` | Per-harness thin wrappers (data from graph) |\n| `packages/adapters/core` | Provider resolver, workspace service |\n| `packages/transport-adapter` | HTTP proxy: protocol translation between harness ↔ provider |\n| `packages/adapters/hooks` | Hook normalization: native events → canonical phases |\n| `packages/babysitter-sdk` | Babysitter SDK: run lifecycle, session binding, MCP tools |\n| `packages/triggers-adapter` | GitHub Action: trigger evaluation + agent dispatch |\n| `packages/kradle` | Kubernetes operator + web UI for cloud deployment |\n| `packages/extensions-adapter` | Plugin generator: unified source → per-harness distributions |\n| `packages/genty/platform` | Standalone babysitter agent (internal harness) |\n\n## Development Workflow\n\n1. **Model in the graph** — Add YAML nodes/edges to `packages/atlas/graph/`\n2. **Query via catalog** — Use `getAgentVersion()`, `getCapabilityFlags()`, etc.\n3. **Test via live-stack** — E2E tests validate real API calls through the full stack\n4. **Evidence loop** — Test results feed back into the graph as experimental evidence\n",
    "documents": []
  },
  "outgoingEdges": [],
  "incomingEdges": [
    {
      "from": "page:docs-development",
      "to": "page:docs-development-01-overview-and-philosophy",
      "kind": "contains_page"
    }
  ]
}