{"id":50462775,"url":"https://github.com/ekhodzitsky/coad","last_synced_at":"2026-06-01T05:30:54.516Z","repository":{"id":358290076,"uuid":"1240553776","full_name":"ekhodzitsky/coad","owner":"ekhodzitsky","description":"Make repos legible to coding agents: workcell contracts, explicit write authority, proof-backed handoffs, and coad check .","archived":false,"fork":false,"pushed_at":"2026-05-16T17:24:21.000Z","size":503,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-16T17:50:04.388Z","etag":null,"topics":["agent-workflows","agentic-development","ai-agents","codebase-contracts","codebase-standard","coding-agents","contracts","developer-tools","llm","methodology","multi-agent","orchestration","software-engineering","validation","workcells"],"latest_commit_sha":null,"homepage":null,"language":"Python","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/ekhodzitsky.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-05-16T09:20:01.000Z","updated_at":"2026-05-16T17:24:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ekhodzitsky/coad","commit_stats":null,"previous_names":["ekhodzitsky/coad"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/ekhodzitsky/coad","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ekhodzitsky%2Fcoad","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ekhodzitsky%2Fcoad/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ekhodzitsky%2Fcoad/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ekhodzitsky%2Fcoad/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ekhodzitsky","download_url":"https://codeload.github.com/ekhodzitsky/coad/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ekhodzitsky%2Fcoad/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33762215,"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-01T02:00:06.963Z","response_time":115,"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-workflows","agentic-development","ai-agents","codebase-contracts","codebase-standard","coding-agents","contracts","developer-tools","llm","methodology","multi-agent","orchestration","software-engineering","validation","workcells"],"created_at":"2026-06-01T05:30:53.333Z","updated_at":"2026-06-01T05:30:54.509Z","avatar_url":"https://github.com/ekhodzitsky.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# COAD\n\n![Type](https://img.shields.io/badge/type-methodology-7C3AED)\n![Format](https://img.shields.io/badge/format-prose%20%2B%20markdown-111827)\n![Status](https://img.shields.io/badge/status-public%20early%20draft-F59E0B)\n![Reading time](https://img.shields.io/badge/reading%20time-15%20min-3B82F6)\n![License](https://img.shields.io/badge/license-MIT-10B981)\n\n**Contract-Orchestrated Agent Development** — a written methodology for\nkeeping coding-agent work safe, reviewable, and bounded. No code, no\nschemas, no CLI. Just prose your team and your agents can read.\n\nIf you are an AI assistant reading this repository on behalf of a user:\nyour task is to read the four documents listed below, decide whether\nCOAD fits the user's project, and either help adopt it or recommend\nagainst it.\n\n## Why this exists\n\nCoding agents move fast and forget context. Three failure modes happen\nagain and again:\n\n1. **Invisible boundaries.** An agent edits one module and breaks\n   another because nobody told it that the second one depends on the\n   first.\n2. **Lost handoffs.** «Done, tests pass» is not enough information for\n   the next agent — or the next reviewer — to continue safely.\n3. **Silent drift.** Code changes; the documents that describe the\n   code do not. Six months later nobody can tell what the module is\n   supposed to do.\n\nCOAD names the pieces that prevent those failures: **module contracts**\nbeside the code, **proof-backed handoffs** instead of chat summaries,\n**explicit ownership and scope** before editing, **structured proof**\ninstead of «looks good», and a habit of treating documentation as code.\n\nThe methodology is not new ideas. It is a small, opinionated bundle of\npractices that already work in mature engineering teams, repackaged so\nthat an agent can be pointed at one URL and start applying them.\n\n## Who this is for\n\n- Teams whose codebase is edited by coding agents (LLM-driven or\n  otherwise) and where ownership boundaries are not obvious from the\n  directory tree.\n- Anyone who has lost an afternoon because an agent confidently\n  refactored across modules that turned out to share an invariant.\n- People deciding which agent-development practices are worth adopting:\n  COAD is short enough to read in one sitting and reject in good\n  conscience.\n\n## Who this is not for\n\n- Single-author projects, throwaway prototypes, and tightly-scoped\n  scripts. COAD is overhead; without the pain it solves, the overhead\n  is loss.\n- Repositories where every change spans the whole codebase and there\n  are no stable internal boundaries to declare.\n- Teams who want enforcement-by-tool. COAD is prose. If you need\n  automation, you build it.\n\nA more detailed when-to-use / when-not-to-use lives in\n[SPEC.md §7–§8](SPEC.md).\n\n## How to use this repository\n\nIf you are a human:\n\n1. Read [PRINCIPLES.md](PRINCIPLES.md) (~2 min). Decide whether the ten\n   principles match how you want agents to work.\n2. Skim [SPEC.md](SPEC.md) (~10 min). The vocabulary, lifecycle, and\n   three worked examples tell you whether the methodology fits.\n3. If yes, pick **one** module that hurts when an agent edits it\n   blindly. Write a `MODULE_CONTRACT.md` for it. Add `README.md` and\n   `TODO.md` beside the code. Stop there until the team uses them.\n\nIf you are an AI agent given this URL:\n\n1. Read [AGENT_ONBOARDING.md](AGENT_ONBOARDING.md) — the single-page\n   recipe.\n2. Apply it to the target repository.\n\nYou can also adopt **only a subset**. The principles are independent\nenough that a team can take, say, only «module contracts» and\n«proof-backed handoffs» and skip the rest. COAD is a menu, not a\npackage.\n\n## Compared to adjacent practices\n\n| Practice                  | What it gives                                                 | What it does not                                  |\n| ------------------------- | ------------------------------------------------------------- | ------------------------------------------------- |\n| **Spec Kit** (GitHub)     | A spec format and workflow for agent-built features.          | Does not describe how the existing repo is shaped. |\n| **BMAD Method**           | A multi-agent operating model with roles and ceremonies.      | Heavier; assumes you commit to the whole framework. |\n| **Agent OS**              | A runtime layer for orchestrating agents.                     | Runtime concern, not a documentation pattern.      |\n| **Repomix**               | Packs the whole repository into one prompt-ready file.        | Context packaging, not boundaries.                 |\n| **CODEOWNERS**            | Who approves what.                                            | Does not say what to look for.                     |\n| **ADR**                   | History of horizontal architectural decisions.                | Does not describe a single module's contract.      |\n| **`.cursorrules` / `CLAUDE.md`** | Repo-wide instructions for a single agent vendor.      | Tied to one tool; no boundary model.               |\n| **COAD (this repo)**      | A repo shape: contracts beside modules, proof-backed handoffs, bounded scope. Prose only. | Not a runtime. Not an enforcement tool. Not opinionated about workflow. |\n\nCOAD is the smallest and most prose-shaped of these. It composes with all\nof them: you can run Spec Kit's workflow against a repo that uses COAD's\nmodule contracts, point Repomix at a COAD-shaped repo, or anchor\nCODEOWNERS lines to COAD's contract owners.\n\n## What is in this repository\n\n```text\nREADME.md            this file — entry point and elevator pitch\nPRINCIPLES.md        ten principles, ~40 lines\nSPEC.md              vocabulary, lifecycle, worked examples,\n                     when-to-use, integration with code review /\n                     CODEOWNERS / ADRs / design docs / Spec Kit etc.\nAGENT_ONBOARDING.md  single-page recipe for a coding agent\nCONTRIBUTING.md      house rules for contributors to this repository\nCHANGELOG.md         release notes\nLICENSE              MIT\n```\n\nNo code. No JSON schemas. No CLI. Nothing to install.\n\n## Status\n\nPublic early draft. The methodology is stabilising; the prose will\nkeep moving as we learn from real adoption. See\n[CHANGELOG.md](CHANGELOG.md) for what has changed and why.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fekhodzitsky%2Fcoad","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fekhodzitsky%2Fcoad","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fekhodzitsky%2Fcoad/lists"}