{"id":50523903,"url":"https://github.com/davidkimai/acp","last_synced_at":"2026-06-03T06:31:48.322Z","repository":{"id":353087117,"uuid":"1217923900","full_name":"davidkimai/acp","owner":"davidkimai","description":"Attention Coordination Protocol (ACP) with Relay as the product surface and Relay Blocks as the modular workflow layer.","archived":false,"fork":false,"pushed_at":"2026-04-22T12:46:43.000Z","size":100,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-22T13:07:03.447Z","etag":null,"topics":["agent-skills","coordination","deliberation","fastify","multi-agent","protocol","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/davidkimai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"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-04-22T11:02:12.000Z","updated_at":"2026-04-22T12:46:47.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/davidkimai/acp","commit_stats":null,"previous_names":["davidkimai/cc"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/davidkimai/acp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidkimai%2Facp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidkimai%2Facp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidkimai%2Facp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidkimai%2Facp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/davidkimai","download_url":"https://codeload.github.com/davidkimai/acp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/davidkimai%2Facp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33852289,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-03T02:00:06.370Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["agent-skills","coordination","deliberation","fastify","multi-agent","protocol","typescript"],"created_at":"2026-06-03T06:31:47.693Z","updated_at":"2026-06-03T06:31:48.317Z","avatar_url":"https://github.com/davidkimai.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ACP\n\nACP stands for **Attention Coordination Protocol**.\n\nThis repository is the main public home for:\n\n- **ACP**: the protocol and canonical object model\n- **Relay**: the first working reference implementation\n- **ACP skills / Relay Blocks**: reusable procedural modules for agent and operator workflows\n\nACP is a protocol-first system for **AI-assisted collective deliberation under bounded attention**. Instead of showing every participant the same undifferentiated feed, ACP treats discussion as a coordination problem: collect contributions, route or summarize them under explicit criteria, release outputs at the right stage, and preserve the resulting trace for audit, review, and downstream analysis.\n\nThis repo also serves as the paper companion for **_Collective Deliberation Is a Skill Issue_**.\n\n## Three ways to use this repo\n\n### 1) Review ACP in 5 minutes\nStart here if you are reading the repository alongside a paper, workshop submission, or review packet.\n\n1. Read [`REVIEWER_START_HERE.md`](REVIEWER_START_HERE.md)\n2. Read [`SUBMISSION_REPO_MAP.md`](SUBMISSION_REPO_MAP.md)\n3. Read [`CLAIMS_AND_NON_CLAIMS.md`](CLAIMS_AND_NON_CLAIMS.md)\n4. Read [`REPRODUCE.md`](REPRODUCE.md) for the copy-paste reproduction path\n5. Read [`protocol/README.md`](protocol/README.md)\n6. Inspect the flagship rehearsal summary surface in [`artifacts/conference/rehearsal/README.md`](artifacts/conference/rehearsal/README.md) and [`artifacts/conference/rehearsal/rehearsal-summary.json`](artifacts/conference/rehearsal/rehearsal-summary.json)\n7. Inspect the skills evidence packet in [`artifacts/evals/skills/final/`](artifacts/evals/skills/final/)\n\n### 2) Run the reference implementation\nStart here if you want to run Relay locally.\n\n```bash\nnpm install\nnpm run dev\n```\n\nHelpful next steps:\n\n```bash\nnpm run demo:bootstrap\nnpm run demo:summary\nnpm run release:smoke\n```\n\n### 3) Inspect benchmarks and study evidence\nStart here if you care about evaluation, portability, or workshop evidence.\n\n- [`benchmarks/README.md`](benchmarks/README.md)\n- [`evals/skills/README.md`](evals/skills/README.md)\n- [`evals/inspect/README.md`](evals/inspect/README.md) for the Inspect AI mirror of the measured skills slice and flagship public-hearing benchmark\n- [`artifacts/evals/inspect/`](artifacts/evals/inspect/) for the real-run mirror summaries and public-hearing comparative packet\n- [`artifacts/completion/final/`](artifacts/completion/final/)\n- [`artifacts/evals/skills/final/`](artifacts/evals/skills/final/)\n- [`skills/CONSTITUTIONAL_SKILLS.md`](skills/CONSTITUTIONAL_SKILLS.md)\n- [`artifacts/skills/constitutional-skills-map.md`](artifacts/skills/constitutional-skills-map.md)\n- [`docs/evaluation/skills-live-provider-budget.md`](docs/evaluation/skills-live-provider-budget.md)\n\n## Paper-companion reproduction\n\nIf you want the shortest copy-paste reproduction path for the load-bearing claims package, run:\n\n```bash\ngit clone https://github.com/davidkimai/acp.git\ncd acp\nnpm install\nexport OPENAI_API_KEY=\"YOUR_KEY_HERE\"\nnpm run reproduce:claims -- --out /tmp/acp-load-bearing-claims\n```\n\nThis path uses **real provider calls** for the skills evidence surfaces. It does **not** use dry runs. When it finishes, start with:\n\n- `/tmp/acp-load-bearing-claims/README.md`\n- `/tmp/acp-load-bearing-claims/summary.json`\n- [`REPRODUCE.md`](REPRODUCE.md) for fuller notes, budgets, and interpretation boundaries\n- [`CLAIMS_AND_NON_CLAIMS.md`](CLAIMS_AND_NON_CLAIMS.md) for the conference-facing claim boundary\n\n## What is in this repository\n\nThis repository combines four layers that are intentionally kept distinct:\n\n1. **Protocol truth**: the ACP contract, canonical schema bundle, compatibility boundaries, and implementer guidance\n2. **Reference implementation truth**: Relay's web app, CLI, API server, storage layer, release gates, and tests\n3. **Procedural skill layer**: reusable ACP skills / Relay Blocks, with a constitutional core for public reasoning, package metadata, compositions, and protocol-adjacent procedural governance attachments\n4. **Evidence layer**: benchmarks, study harnesses, rehearsal bundles, audits, and curated claim-bearing artifacts\n\nIn practice, that means this repo includes:\n\n- the ACP schema bundle and compatibility matrix\n- a working web app, CLI, and local API server\n- seeded demo data for intervention vs baseline walkthroughs\n- benchmark and replay harnesses\n- adopter and runner proof surfaces beyond the browser UI\n- reusable skills and compositions for agent/operator workflows\n- completion audits, rehearsal bundles, and skills-study artifacts\n\n## What Relay currently does\n\nRelay supports two comparable discussion conditions built on the same cycle model:\n\n- `intervention`: routed digests with explanations and review traces\n- `baseline_thread`: chronological thread presentation on the same cycle shell\n\nAcross those conditions, Relay already supports:\n\n- cycle creation and lifecycle control\n- participant contribution, response, and feedback capture\n- routing decisions and digest production for intervention cycles\n- audit events, telemetry, and export generation\n- inspection through both the web app and the CLI\n\n## Source-of-truth hierarchy\n\nIf files disagree, use this order:\n\n1. **Protocol semantics**: [`protocol/`](protocol/) and [`docs/specs/`](docs/specs/)\n2. **Typed implementation semantics**: [`src/core/`](src/core/) and implementation code under [`src/`](src/)\n3. **Operational and evaluation material**: [`docs/`](docs/), [`benchmarks/`](benchmarks/), [`evals/`](evals/), [`artifacts/`](artifacts/)\n4. **Skills**: procedural execution aids, not the protocol itself\n\nA shorter repo map is available in [`AGENTS.md`](AGENTS.md).\n\n## Fast local setup\n\nRequirements:\n\n- Node.js 20+\n\nInstall and run:\n\n```bash\nnpm install\nnpm run build\nnpm run typecheck\nnpm test\nnpm run dev\n```\n\nDefault local settings:\n\n- host: `127.0.0.1`\n- port: `4317`\n- data directory: `.acp-data/`\n\nEnvironment variables:\n\n- `ACP_HOST`\n- `ACP_PORT`\n- `ACP_DATA_DIR`\n\n## Reproduce the main evidence surfaces\n\nFor the full paper-companion reproduction path, including real provider-backed skills results, use [`REPRODUCE.md`](REPRODUCE.md).\n\nUse repo-local outputs only when you intentionally want to refresh tracked artifacts. For ordinary inspection, prefer temporary output paths.\n\n### Demo bundle\n\n```bash\nnpm run demo:bootstrap\nnpm run demo:summary\n```\n\nSee [`demo/README.md`](demo/README.md).\n\n### Technical and release checks\n\n```bash\nnpm run release:smoke\nnpm run release:gate\nnpm run completion:audit -- --out /tmp/acp-completion-audit\n```\n\n### Flagship benchmark / rehearsal surface\n\n```bash\nnpm run benchmark:compare -- --class public-hearing-triage\nnpm run conference:rehearsal\n```\n\nPrimary artifacts:\n\n- [`artifacts/conference/rehearsal/rehearsal-summary.json`](artifacts/conference/rehearsal/rehearsal-summary.json)\n- [`artifacts/conference/rehearsal/README.md`](artifacts/conference/rehearsal/README.md)\n\n### Skills structural audit and study surfaces\n\n```bash\nnpm run skills:audit -- --out /tmp/acp-skills-audit\nnpm run skills:compare -- --out /tmp/acp-skills-comparative\n```\n\nFor the current claims package, read:\n\n- [`artifacts/evals/skills/final/reviewer-start-here.md`](artifacts/evals/skills/final/reviewer-start-here.md)\n- [`artifacts/evals/skills/final/skills-v3-claims-memo.md`](artifacts/evals/skills/final/skills-v3-claims-memo.md)\n- [`artifacts/evals/skills/final/skills-v3-results-overview.md`](artifacts/evals/skills/final/skills-v3-results-overview.md)\n\n## Optional live-provider reproduction\n\nSome evaluation paths make real provider calls and incur cost.\n\nBefore running them, read:\n\n- [`docs/evaluation/skills-live-provider-budget.md`](docs/evaluation/skills-live-provider-budget.md)\n\nModel policy for these runs:\n\n- default: `gpt-5.4-mini`\n- arbitration / hard cases only: `gpt-5.4`\n\nSet credentials through environment variables such as `OPENAI_API_KEY`. Do not commit secrets or paste them into tracked artifacts.\n\n## Claims boundary\n\nThis repository is intended to support a conservative, inspectable submission package.\n\nWhat the current repo supports well:\n\n- ACP as a protocol-first coordination system\n- Relay as a functioning reference implementation\n- benchmark, audit, and rehearsal surfaces that preserve inspectable traces\n- a procedural skills layer with structural audits and behavioral-study artifacts\n\nWhat the current repo does **not** justify on its own:\n\n- field efficacy claims\n- claims that fairness is solved\n- claims of institutional legitimacy by default\n- broad superiority claims across all tasks and settings\n- operator-utility claims without human review evidence\n\nFor the current bounded non-claims, see [`artifacts/evals/skills/final/skills-v3-non-claims.md`](artifacts/evals/skills/final/skills-v3-non-claims.md).\n\n## Repository layout\n\n```text\nsrc/                 server, API, core types, services, CLI, study substrate\npublic/              Relay web app\nprotocol/            schema bundle, examples, discovery, compatibility matrix\nskills/              ACP skills / Relay Blocks, manifests, compositions\nbenchmarks/          seeded benchmark classes and comparison harnesses\nevals/               evaluation fixtures, studies, and task sets\ndemo/                synthetic demo bundle for intervention vs baseline walkthroughs\nrunners/             batch and API-driven proof surfaces\nadopters/            external-adopter starter example(s)\nscripts/             release, reporting, benchmarks, skills, and conference tooling\ndocs/specs/          normative product, protocol, and platform specs\ndocs/compatibility/  practical compatibility notes for implementers\ndocs/evaluation/     evaluation instruments and live-provider budget policy\nartifacts/           curated claim-bearing outputs checked into the repo\n```\n\n## Additional entry points\n\n- [`protocol/EXTERNAL_IMPLEMENTER_GUIDE.md`](protocol/EXTERNAL_IMPLEMENTER_GUIDE.md)\n- [`docs/README.md`](docs/README.md)\n- [`benchmarks/README.md`](benchmarks/README.md)\n- [`demo/README.md`](demo/README.md)\n- [`artifacts/README.md`](artifacts/README.md)\n\n## Naming note\n\n- **ACP** = the protocol\n- **Relay** = the first implementation\n- **ACP skills / Relay Blocks** = the reusable procedural layer\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidkimai%2Facp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdavidkimai%2Facp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdavidkimai%2Facp/lists"}