Groundwork is a methodology plugin for runa, a cognitive runtime for AI coding agents. It encodes opinions about how software should be built into protocols, skills, and artifact schemas that a runa instance orchestrates. It is not a runtime, a CLI, or a framework — it is a methodology definition.
Groundwork serves teams that use AI coding agents for software delivery. It connects the stages from problem framing through shipped change so that agent work traces from requirement to merged code, completion claims require evidence, and progress survives session boundaries.
For what methodology plugins are and how runa executes them, see runa's core concepts.
Work moves through two phases connected by the work-unit artifact.
Planning takes an external request and produces work-units. Survey examines what actually needs doing; decompose breaks that into work units with acceptance criteria and dependency edges.
Execution takes one work-unit and carries it through to a merged increment: take claims the work-unit and opens the session → specify writes the behavior contract as Given/When/Then scenarios → plan converges on a decision-complete design → implement executes through RED-GREEN-REFACTOR → verify gates completion with evidence → document ensures accuracy → submit packages the change → land merges and closes the loop.
Each protocol produces an artifact that the next protocol requires.
→ docs/architecture/connecting-structure.md
Skills operate across the topology as cross-cutting disciplines and stage-specific judgment:
- orient — the methodology map that connects protocols and skills
- reckon — first-principles reasoning when creating or analyzing
- debug — root cause investigation when failures appear
- resolve — structural friction resolution when obstacles impede
- research — external evidence gathering when facts are missing
- contract — behavior traceability through execution
- code-review — review judgment for submitted change proposals
Not every piece of work needs every stage. A bug with an existing work-unit enters
at execution. A new capability enters at planning. The constraint is sequence,
not completeness.
→ skills/orient/SKILL.md
For how runa orchestrates this topology at runtime, see the interface contract.
Runa-served agents consume Groundwork through the methodology mount. Interactive Claude Code and Codex sessions can install the same skills and protocols into their local discovery directories from a pinned Groundwork checkout:
git checkout --detach v0.2.0
scripts/groundwork-install installThe first release containing scripts/groundwork-install is v0.2.0.
The installer writes user-owned entries only, with no root or sudo requirement:
~/.claude/skills/{name}/~/.agents/skills/{name}/~/.groundwork/
Every directory under skills/ is copied as a skill entry. Every directory
under protocols/ is copied as a skill-shaped entry with PROTOCOL.md
projected to SKILL.md and an interactive artifact delivery adapter inserted
near the top of the installed protocol. The adapter tells an interactive agent
how to present the produced artifact body to the human instead of calling the
runa MCP artifact tool. Installed entries are copies, not source-checkout
symlinks, so later changes to the checkout do not drift into the active
discovery surface.
When manifest.toml, mechanics/, and the forge-operation resolver are
present, the installer also projects a managed runtime bundle under
~/.groundwork/. The bundle contains the manifest, mechanic library, resolver
module, and bin/groundwork-mechanic, so installed protocol sessions can
resolve forge-invariant operations through the active GROUNDWORK_FORGE_TYPE
configuration without reaching back into the source checkout. Installed
protocol copies reference the managed resolver path directly, so users do not
need to add ~/.groundwork/bin to PATH.
The early-arc tracker operations are forge-invariant at the call site and
forge-tagged in the mechanic library: create-ticket, read-ticket,
claim-work-unit, and record-progress resolve to either GitHub issue
mechanics or SourceHut ticket mechanics. Ticket creation emits the
forge-assigned identity needed for a work-unit.handle: GitHub emits
forge_tag, issue url, and issue number; SourceHut emits forge_tag,
tracker_id, and ticket number. The mechanics validate the expected API or
GraphQL result field before accepting a response, so an HTTP- or CLI-successful
response that contains application errors or omits the expected operation
result is rejected.
Secret mechanic parameters must be bound from an environment variable rather
than from NAME=VALUE argv bindings. For example, pass
--secret-env token=WEFORGE_OPERATOR_PAT to bind a secret token parameter
from the current process environment without placing the secret value in the
resolver command line.
Forge deployment identity is also supplied by environment contract, not by
mechanic call-site bindings. Mechanics mark deployment-resolved parameters with
deployment_value, and groundwork-mechanic derives those values from these
atoms:
| Variable | Holds | Example | Forge-assigned? |
|---|---|---|---|
GROUNDWORK_FORGE_TYPE |
active forge selector, defaulting to github |
sourcehut |
no |
GROUNDWORK_FORGE_ENDPOINT |
deployment host used to derive service hosts | weforge.build |
no |
GROUNDWORK_FORGE_OWNER |
tracker/repo owner handle | operator |
no |
GROUNDWORK_FORGE_NAME |
tracker/repo name | weforge |
no |
GROUNDWORK_FORGE_TRACKER_ID |
tracker integer ID | 4 |
yes |
GROUNDWORK_FORGE_REPO_ID |
git repo integer ID | 42 |
yes |
For SourceHut, the resolver derives todo_query_url as
https://todo.<endpoint>/query, git_query_url as
https://git.<endpoint>/query, and ssh_remote as
git@git.<endpoint>:~<owner>/<name>, while tracker_id and repo_id come
directly from their atoms. For GitHub, it derives repository as
<owner>/<name>. The atoms are the only deployment facts; composed endpoints
and remotes are not separate configuration values.
The cross-repo seam for this ticket identity is documented in
docs/architecture/connecting-structure.md.
Groundwork owns the schema-as-contract shape of work-unit.handle, the
mechanics that produce handles from active deployment identity, and the
decompose delivery rules. runa owns scoped runtime enforcement: exact recorded
--work-unit ids, tracker-handle consistency, duplicate-root rejection, and
active deployment agreement. Cross-deployment work is composed from separate
sessions; a handle never overrides the active deployment.
The source checkout must be clean and pinned at a tag or full commit SHA. The command refuses branch checkouts because a branch is a moving source. To update to a different pinned Groundwork version, check out that ref and run:
scripts/groundwork-install syncsync converges the discovery directories to the new pinned source, including
removing entries that no longer exist upstream. scripts/groundwork-install status reports the recorded install state, and scripts/groundwork-install uninstall removes only entries the command created.
Methodology authors who develop Groundwork itself and want their working branch
reflected in the live discovery surface can pass --from-branch to install or
sync the current branch HEAD instead of a detached pinned ref:
scripts/groundwork-install sync --from-branchThe checkout must still be clean — --from-branch relaxes only the pinned-ref
requirement, not the clean-checkout requirement, so the recorded source-sha
always identifies a real commit. Because a branch is a moving source, this is an
opt-in for development; the default still requires a pinned tag or commit SHA.
Ownership is tracked in both a per-entry marker file and an XDG state file at
${XDG_STATE_HOME:-~/.local/state}/groundwork-install/interactive-install.tsv.
Pre-existing entries, including unofficial symlinks with the same names, are
reported as unmanaged conflicts rather than overwritten or adopted. When the
state file records ownership but the marker is missing at a deletion boundary,
the command fails and leaves state intact so the operator can inspect the
disagreement before anything irreversible happens.
Prerequisites are the stock command-line tools expected on Fedora CoreOS for
this workflow: bash, git, and POSIX file utilities such as cp, find,
mkdir, mv, and rm.
Run the narrowed Step 1 methodology conformance runner with:
python -m tooling.conformanceBy default it checks manifest.toml, source-tree workflow contracts and
mechanics when those directories exist, and all JSON Schema definitions under
schemas/. Pass files or directories as arguments to check explicit
C-2/C-3/C-4/C-5 units and aggregate all failures before returning a non-zero
exit status. Directory arguments use the same discovery rules as the default
runner: manifest.toml, workflow-contracts/ and mechanics/ TOML units,
plus schemas/*.schema.json. Explicit file arguments that do not classify as
conformance units still fail loudly.
The C-5 manifest check validates the outcome-routing substrate used by
required-choice protocol outputs: top-level [[outcome_types]] entries must
resolve to declared artifact types, [[protocols.required_output_choices]]
members must be registered outcome types, and successor triggers that route on
an outcome must use on_artifact, while successor triggers must not target a
disposition-agnostic output of an outcome-bearing protocol through any trigger
form or composite trigger.
It also validates forge-tagged C-3 mechanic bindings. When a manifest
[[mechanics]] entry declares forge_tags = [...], each tag must resolve to
[[forge_tags]] and exactly one mechanics/**/*.toml file whose name and
forge_tag match that operation/tag pair.
These are the methodology choices embedded in groundwork's protocols and skills. Each traces to the file where it lives.
The work-unit graph is working memory. Agent sessions end, context windows
close, agents rotate. The work-unit graph is the persistence layer that survives
those boundaries. Multi-session progress depends on the graph, not on agent
memory.
→ docs/architecture/work-unit-model.md
Sovereignty. Every handoff passes outcomes — what must be true — never
implementation steps. Work-units define acceptance criteria, not procedure. Plans
define interfaces and decisions, not scripts to follow.
→ protocols/decompose/PROTOCOL.md
Behavior is the thread. The behavior contract written during specify traces
through every subsequent stage. Plans link design decisions to behavior
scenarios. Tests verify named scenarios. Verification cites behavior-level
evidence. Landing records what coverage shipped.
→ protocols/specify/PROTOCOL.md,
skills/contract/SKILL.md
Evidence before assertion. No completion claims without fresh verification
evidence. No fixes without root cause investigation. No implementation plans
without grounded constraints.
→ protocols/verify/PROTOCOL.md,
skills/debug/SKILL.md
Test-driven execution. No production code without a failing test first.
Each test fails first, and for the right reason. Only the minimum code to pass
gets written. Code written before its test gets deleted and restarted.
→ protocols/implement/PROTOCOL.md
Code is ground truth. When documentation and code disagree, code behavior
is descriptive truth. Documentation is a claim that must be verified against
the code.
→ protocols/document/PROTOCOL.md
Documentation obligation. User-facing changes carry documentation
requirements. Documentation ships in the same PR as the code that caused it.
Drifted documentation compounds.
→ protocols/document/PROTOCOL.md,
skills/orient/SKILL.md
Root cause before fixes. No fix without an established root cause. After
three failed fix attempts, the architecture is under question, not the
symptoms.
→ skills/debug/SKILL.md
Friction is structural. Workarounds compound debt. Operational friction — a
missing tool, broken configuration, stale convention — gets resolved
structurally before work continues. Friction that exceeds side-quest scope
becomes a work-unit.
→ skills/resolve/SKILL.md
| Path | Contains |
|---|---|
manifest.toml |
Manifest: artifact types, protocol topology, trigger conditions |
protocols/ |
Protocol definitions for methodology stages |
skills/ |
Skills for orientation, cross-cutting disciplines, and stage-specific judgment |
schemas/ |
JSON Schema contracts for artifacts and authoring substrates |
tooling/ |
Authoring-time parsers and validators |
docs/architecture/ |
Topology design rationale and work-unit state model |
docs/authoring/ |
Follow-direct guides for methodology authors |
For how these pieces compose into a methodology plugin, see runa's methodology authoring guide.