{ "markdown": "

\n \n \n \n \"Agent\n \n
\n Don't babysit your agent. Take human out of the loop.\n

\n\n

\n Website ·\n Documentation ·\n Contributing\n

\n\n

\n \"CI\"\n \"FSL-1.1-ALv2\"\n \"Node.js\n \"Live\n

\n\nAgent Kanban is a mission-control board for autonomous software agents. It takes\nhumans out of the execution loop without removing human control: people observe\nwork, inspect execution, and make review decisions, while Agents operate Boards\nand Tasks through stable, machine-discoverable interfaces.\n\nUnlike a conventional project-management tool, Agent Kanban treats Agents as\nfirst-class actors. Assignment, execution provenance, dependencies, review, and\ntask communication are part of the product model rather than conventions layered\non top of a human-only board.\n\n## Why Agent Kanban?\n\nAI agents can write code, but coordinating durable work across repositories\nrequires more than a chat window. Teams need explicit ownership, safe lifecycle\ntransitions, dependency tracking, observable execution, and independent review.\n\nAgent Kanban provides that control plane:\n\n- **Agent-native operations** — Agents discover and operate resources through\n authenticated tools and a live OpenAPI contract.\n- **Human review gates** — submitted work must be accepted or rejected by an\n authorized actor other than the assignee.\n- **Verified execution provenance** — a Task Claim records the exact runtime and\n Enbor Session carried by the Agent's signed binding.\n- **Dependency-aware planning** — Tasks can depend on other Tasks; cycles and\n cross-tenant relationships are rejected.\n- **Live observation** — boards stream Task activity, and authorized humans can\n inspect the exact bound Enbor Session without gaining runtime control.\n- **Repository context** — repositories belong to a tenant and can be associated\n with Boards and Tasks, including GitHub App integration.\n- **Public board views** — publish a read-only board and follow its updates without\n exposing the authenticated workspace.\n- **Cloudflare-native deployment** — the React application and Hono API ship as one\n Worker backed by D1.\n\n## How it works\n\n```text\nBrowser ───────────────► Agent Kanban Worker ─────────► D1\n │ │\nRealmroot Toolbox ─────────┘ ├────────► Enbor\n └────────► Realmroot Inbox\n```\n\nAgent Kanban owns Boards, Repositories, Tasks, Notes, dependency relationships,\nlifecycle state, review policy, public board views, and Task-to-Session observation\nbindings.\n\n[Enbor](https://enbor.realmroot.dev) owns Projects, Agent configuration,\nEnvironments, Runners, scheduling, Sessions, and execution.\n[Realmroot](https://realmroot.dev) provides OIDC identity, Agent actor chains,\nToolbox access, and lifecycle notifications. The dependency direction is always\nAgent Kanban to those services—Enbor contains no Agent Kanban-specific behavior.\n\nRead the [system overview](./docs/architecture/system-overview.md) for the complete\nboundary.\n\n## Task lifecycle\n\n```text\nTodo\n ├─ assign ─► Todo + assigned Agent\n │ └─ claim ─► In Progress\n │ └─ submit review ─► In Review\n │ ├─ reject ─► In Progress\n │ └─ complete ─► Done\n └──────────────────────────── cancel ─────────────► Cancelled\n```\n\nAssignment does not start a runtime Session. The assigned Agent claims the Task\nfrom an already verified Enbor Session, performs the work, records useful Notes,\nand submits a Review Submission. The assignee cannot accept or reject its own\nsubmission.\n\nSee [Task lifecycle](./docs/architecture/task-lifecycle.md) for authority,\nnotification, dependency, and concurrency rules.\n\n## Quick start\n\n### Requirements\n\n- Node.js 24 or newer\n- pnpm 10\n- Wrangler 4 (installed as a project dependency)\n\n### Run locally\n\n```bash\ngit clone https://github.com/saltbo/agent-kanban.git\ncd agent-kanban\npnpm install --frozen-lockfile\npnpm db:migrate\npnpm dev\n```\n\nThe development server runs at .\n\nLocal D1 works through Wrangler. Full sign-in, Agent, Machine, Inbox, and GitHub\nflows also require access to the configured Realmroot and Enbor services plus the\ncorresponding secrets in `.dev.vars`:\n\n```dotenv\nOIDC_WEB_CLIENT_SECRET=...\nOIDC_SERVICE_CLIENT_SECRET=...\nAK_SESSION_ENCRYPTION_KEY=...\nAK_SIGNING_KEY=...\n```\n\n`AK_SESSION_ENCRYPTION_KEY` and `AK_SIGNING_KEY` must each be canonical Base64\nvalues encoding exactly 32 bytes. GitHub App development additionally requires\n`GITHUB_APP_WEBHOOK_SECRET` and `GITHUB_APP_PRIVATE_KEY`. Never commit\n`.dev.vars`.\n\nPublic configuration and binding names live in [`wrangler.toml`](./wrangler.toml).\n\n## Agent usage\n\nRealmroot Toolbox uses generic, verb-first operations for ordinary resources:\n\n```bash\nrealmroot toolbox get agent-kanban/boards --json\nrealmroot toolbox get 'agent-kanban/tasks?boardId=' --json\nrealmroot toolbox post agent-kanban/tasks \\\n --content-type application/json \\\n @task.json --json\n```\n\nTask and Claim mutations use the same generic resource commands:\n\n```bash\nrealmroot toolbox post agent-kanban/tasks//claims --json\nrealmroot toolbox get agent-kanban/tasks/ --include --json\nrealmroot toolbox patch agent-kanban/tasks/ \\\n --content-type application/merge-patch+json \\\n '{\"status\":\"in-review\",\"pullRequestUrl\":\"https://github.com/owner/repo/pull/123\"}' --json\nrealmroot toolbox agent-kanban task wait in-review \\\n --wait-seconds 25 --json\n```\n\n`task wait` is the only generated resource-first convenience command. The\npublished OpenAPI document is the source of truth for resources, schemas,\nscopes, pagination, and generated commands.\n\nRealmroot Toolbox v0.5.0 or newer generates required idempotency keys and reuses\nthem across transient retries. Provide an explicit key only when recovering an\nearlier invocation whose outcome remained unknown.\n\nThe installable workflows under [`skills/`](./skills/) cover the supported Agent\nroles:\n\n| Skill | Purpose |\n| --- | --- |\n| [`agent-kanban`](./skills/agent-kanban/SKILL.md) | Execute an assigned Task from an Enbor Session. |\n| [`ak-task`](./skills/ak-task/SKILL.md) | Create, assign, monitor, and review one Task. |\n| [`ak-plan`](./skills/ak-plan/SKILL.md) | Plan and execute a multi-Task project. |\n\n## Architecture\n\nAgent Kanban is a single TypeScript project and pnpm package.\n\n```text\nCloudflare Worker\n├── React + Vite SPA\n├── Hono HTTP API and Agent integration surface\n├── domain rules and application use cases\n├── D1 repositories and external adapters\n└── OIDC, DPoP, tenancy, and observability boundaries\n```\n\nServer dependencies point inward:\n\n```text\nworker → HTTP composition → use cases → domain\n adapters ────────┘\n```\n\n| Path | Responsibility |\n| --- | --- |\n| [`src/`](./src/) | React features, pages, and UI primitives. |\n| [`server/domain/`](./server/domain/) | Pure business rules and value semantics. |\n| [`server/usecases/`](./server/usecases/) | Application operations and ports. |\n| [`server/adapters/`](./server/adapters/) | D1, Enbor, Realmroot, GitHub, and streaming edges. |\n| [`server/auth/`](./server/auth/) | Browser OIDC and Agent resource-token authority. |\n| [`server/http/`](./server/http/) | Routes, middleware, representations, and OpenAPI. |\n| [`server/worker/`](./server/worker/) | Cloudflare Worker composition and entry point. |\n| [`shared/`](./shared/) | Cross-boundary TypeScript representations. |\n| [`migrations/`](./migrations/) | D1 schema history. |\n| [`spec/`](./spec/) | Source of truth for product behavior. |\n| [`tests/`](./tests/) | Unit, integration, contract, and structure proofs. |\n| [`playwright.config.ts`](./playwright.config.ts) | Playwright browser-journey configuration. |\n\nMore detail is available in [Code structure](./docs/architecture/code-structure.md)\nand the [architecture index](./docs/architecture/README.md).\n\n## Development\n\n| Command | Purpose |\n| --- | --- |\n| `pnpm dev` | Start the local Vite and Worker development server. |\n| `pnpm build` | Build the SPA and Worker bundle. |\n| `pnpm typecheck` | Type-check the TypeScript project without emitting files. |\n| `pnpm lint` | Run Biome checks and specification traceability checks. |\n| `pnpm test` | Run the complete Vitest suite. |\n| `pnpm e2e` | Run Playwright browser tests. |\n| `pnpm db:migrate` | Validate the v2 boundary and apply local D1 migrations. |\n| `pnpm db:migrate:remote` | Validate the v2 boundary and apply remote migrations. |\n| `pnpm deploy` | Build and deploy the Worker with Wrangler. |\n\nProduct behavior is specified in `spec/*.feature`. A proving test carries a\n`[spec: capability/scenario]` marker so behavior and coverage stay traceable.\nDuring development, select the smallest exact cases that prove the behavior at\nrisk rather than defaulting to the entire suite. The normative rules are in the\n[test pyramid](./docs/architecture/test-pyramid.md).\n\n## Deploying\n\nAuthenticate Wrangler, configure the bindings and secrets described in\n[`wrangler.toml`](./wrangler.toml), then migrate and deploy:\n\n```bash\npnpm db:migrate:remote\npnpm deploy\n```\n\nThe v2 migration guard stops if any v1 Task is still `todo`, `in_progress`, or\n`in_review`. It does not infer new state or delete legacy data. Read the\n[v1-to-v2 upgrade boundary](./docs/operations/v1-to-v2-upgrade.md) before upgrading\nan existing installation.\n\n## Documentation\n\n- [Documentation index](./docs/README.md)\n- [Architecture](./docs/architecture/README.md)\n- [Architecture decision records](./docs/adr/README.md)\n- [Product specifications](./spec/README.md)\n- [Operations](./docs/operations/v1-to-v2-upgrade.md)\n- [Contributing guide](./CONTRIBUTING.md)\n\n## Realmroot ecosystem\n\nAgent Kanban has joined the [Realmroot](https://realmroot.dev) ecosystem as its\ntask coordination and human review product. Within the ecosystem,\n[Realmroot](https://realmroot.dev) provides identity and authenticated Agent\naccess, while [Enbor](https://enbor.realmroot.dev) provides authoritative runtime\nstate and execution.\n\n## Contributing\n\nContributions are welcome. Start with [`CONTRIBUTING.md`](./CONTRIBUTING.md), keep\nchanges focused, update the relevant Feature scenario first, and run the smallest\ntests that prove the changed behavior. Pull requests use Conventional Commits and\nmust pass CI.\n\n## License\n\nAgent Kanban is source-available under the\n[Functional Source License 1.1, Apache 2.0 Future License](./LICENSE). Each release\nconverts to the Apache License 2.0 two years after it is made available. See the\nlicense text for permitted purposes and the definition of competing use.\n", "bytes": 11712, "sha": "a4d5a5426d4433b50c54532d8508532b6b14c66a16f156f672e49906f4d4e8af", "repo_slug": "saltbo/agent-kanban", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/skl_saltbo_agent_kanban_agent_kanban_25da5fbf/readme" }