{"id":49154320,"url":"https://github.com/tesserine/groundwork","last_synced_at":"2026-04-22T08:03:54.304Z","repository":{"id":341917632,"uuid":"1171790987","full_name":"tesserine/groundwork","owner":"tesserine","description":"Open-source contributor methodology for AI agents. The first methodology plugin for runa.","archived":false,"fork":false,"pushed_at":"2026-04-18T17:31:18.000Z","size":585,"stargazers_count":0,"open_issues_count":12,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-18T18:27:50.109Z","etag":null,"topics":["ai-agents","autonomous-agents","methodology","tesserine"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tesserine.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":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-03-03T16:01:39.000Z","updated_at":"2026-04-13T14:28:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tesserine/groundwork","commit_stats":null,"previous_names":["pentaxis93/groundwork","tesserine/groundwork"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/tesserine/groundwork","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tesserine%2Fgroundwork","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tesserine%2Fgroundwork/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tesserine%2Fgroundwork/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tesserine%2Fgroundwork/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tesserine","download_url":"https://codeload.github.com/tesserine/groundwork/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tesserine%2Fgroundwork/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32126711,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-22T07:37:52.372Z","status":"ssl_error","status_checked_at":"2026-04-22T07:37:51.635Z","response_time":58,"last_error":"SSL_read: 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":["ai-agents","autonomous-agents","methodology","tesserine"],"created_at":"2026-04-22T08:03:53.577Z","updated_at":"2026-04-22T08:03:54.296Z","avatar_url":"https://github.com/tesserine.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Groundwork\n\nGroundwork is a methodology plugin for [runa](https://github.com/tesserine/runa),\na cognitive runtime for AI coding agents.\nIt encodes opinions about how software should be built into protocols, skills,\nand artifact schemas that a runa instance orchestrates. It is not a runtime, a\nCLI, or a framework — it is a methodology definition.\n\nGroundwork serves teams that use AI coding agents for software delivery. It\nconnects the stages from problem framing through shipped change so that agent\nwork traces from requirement to merged code, completion claims require evidence,\nand progress survives session boundaries.\n\nFor what methodology plugins are and how runa executes them, see runa's\n[core concepts](https://github.com/tesserine/runa#core-concepts).\n\n## The Shape of the Methodology\n\nWork moves through two phases connected by the work-unit artifact.\n\n**Planning** takes an external request and produces work-units.\nSurvey examines what actually needs doing; decompose breaks that into work\nunits with acceptance criteria and dependency edges.\n\n**Execution** takes one work-unit and carries it through to a merged increment:\ntake claims the work-unit and opens the session → specify writes the behavior\ncontract as Given/When/Then scenarios → plan converges on a decision-complete\ndesign → implement executes through RED-GREEN-REFACTOR → verify gates\ncompletion with evidence → document ensures accuracy → submit packages the\nchange → land merges and closes the loop.\n\nEach protocol produces an artifact that the next protocol requires.\n→ [`docs/architecture/connecting-structure.md`](docs/architecture/connecting-structure.md)\n\nSix skills operate across the topology:\n\n- **orient** — the methodology map that connects protocols and skills\n- **reckon** — first-principles reasoning when creating or analyzing\n- **debug** — root cause investigation when failures appear\n- **resolve** — structural friction resolution when obstacles impede\n- **research** — external evidence gathering when facts are missing\n- **contract** — behavior traceability through execution\n\nNot every piece of work needs every stage. A bug with an existing work-unit enters\nat execution. A new capability enters at planning. The constraint is sequence,\nnot completeness.\n→ [`skills/orient/SKILL.md`](skills/orient/SKILL.md)\n\nFor how runa orchestrates this topology at runtime, see the\n[interface contract](https://github.com/tesserine/runa/blob/main/docs/interface-contract.md).\n\n## What Groundwork Believes\n\nThese are the methodology choices embedded in groundwork's protocols and skills.\nEach traces to the file where it lives.\n\n### How work is understood\n\n**The work-unit graph is working memory.** Agent sessions end, context windows\nclose, agents rotate. The work-unit graph is the persistence layer that survives\nthose boundaries. Multi-session progress depends on the graph, not on agent\nmemory.\n→ [`docs/architecture/work-unit-model.md`](docs/architecture/work-unit-model.md)\n\n**Sovereignty.** Every handoff passes outcomes — what must be true — never\nimplementation steps. Work-units define acceptance criteria, not procedure. Plans\ndefine interfaces and decisions, not scripts to follow.\n→ [`protocols/decompose/PROTOCOL.md`](protocols/decompose/PROTOCOL.md)\n\n### How work is executed\n\n**Behavior is the thread.** The behavior contract written during specify traces\nthrough every subsequent stage. Plans link design decisions to behavior\nscenarios. Tests verify named scenarios. Verification cites behavior-level\nevidence. Landing records what coverage shipped.\n→ [`protocols/specify/PROTOCOL.md`](protocols/specify/PROTOCOL.md),\n[`skills/contract/SKILL.md`](skills/contract/SKILL.md)\n\n**Evidence before assertion.** No completion claims without fresh verification\nevidence. No fixes without root cause investigation. No implementation plans\nwithout grounded constraints.\n→ [`protocols/verify/PROTOCOL.md`](protocols/verify/PROTOCOL.md),\n[`skills/debug/SKILL.md`](skills/debug/SKILL.md)\n\n**Test-driven execution.** No production code without a failing test first.\nEach test fails first, and for the right reason. Only the minimum code to pass\ngets written. Code written before its test gets deleted and restarted.\n→ [`protocols/implement/PROTOCOL.md`](protocols/implement/PROTOCOL.md)\n\n**Code is ground truth.** When documentation and code disagree, code behavior\nis descriptive truth. Documentation is a claim that must be verified against\nthe code.\n→ [`protocols/document/PROTOCOL.md`](protocols/document/PROTOCOL.md)\n\n**Documentation obligation.** User-facing changes carry documentation\nrequirements. Documentation ships in the same PR as the code that caused it.\nDrifted documentation compounds.\n→ [`protocols/document/PROTOCOL.md`](protocols/document/PROTOCOL.md),\n[`skills/orient/SKILL.md`](skills/orient/SKILL.md)\n\n### How obstacles are handled\n\n**Root cause before fixes.** No fix without an established root cause. After\nthree failed fix attempts, the architecture is under question, not the\nsymptoms.\n→ [`skills/debug/SKILL.md`](skills/debug/SKILL.md)\n\n**Friction is structural.** Workarounds compound debt. Operational friction — a\nmissing tool, broken configuration, stale convention — gets resolved\nstructurally before work continues. Friction that exceeds side-quest scope\nbecomes a work-unit.\n→ [`skills/resolve/SKILL.md`](skills/resolve/SKILL.md)\n\n## What the Repo Contains\n\n| Path | Contains |\n|------|----------|\n| [`manifest.toml`](manifest.toml) | Manifest: artifact types, protocol topology, trigger conditions |\n| [`protocols/`](protocols/) | 10 protocol definitions — one per stage |\n| [`skills/`](skills/) | 6 skills — orientation and cross-cutting disciplines |\n| [`schemas/`](schemas/) | JSON Schema contracts for each artifact type |\n| [`docs/architecture/`](docs/architecture/) | Topology design rationale and work-unit state model |\n\nFor how these pieces compose into a methodology plugin, see runa's\n[methodology authoring guide](https://github.com/tesserine/runa/blob/main/docs/methodology-authoring-guide.md).\n\n## License\n\n[MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftesserine%2Fgroundwork","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftesserine%2Fgroundwork","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftesserine%2Fgroundwork/lists"}