Skip to main content
Glama

Groundwork

Your product evidence, in your repo, written by your own agent.

Groundwork lets Claude Code (or any MCP agent) keep customer insights, hypotheses, experiments, findings and requirements as linked Markdown files in a groundwork/ folder. Every requirement traces back to the findings, experiments and customer quotes behind it.

insight ──▶ hypothesis ──▶ experiment ──▶ finding ──▶ requirement
"I gave up    "Guided import   pilot, 10      "activation    "Guided CSV
 after 20      will lift        accounts:      61% vs 38%"    import"
 minutes"      activation"      validated"
  • No account, no API keys, no server. Your agent does the thinking. Groundwork checks the data, keeps links valid and computes experiment verdicts.

  • Plain files. Read them, diff them, review them in pull requests, and keep them as long as you like.

  • Traceability. Ask "why are we building this?" and get the full evidence chain, or check it in CI with groundwork validate.

Quickstart (2 minutes)

Claude Code

In your project folder:

claude mcp add groundwork -- npx -y groundwork-mcp

Or install the plugin, which adds the MCP server and a skill that teaches Claude when to use it:

/plugin marketplace add IdeatorlabsAB/groundwork
/plugin install groundwork@groundwork

Codex

codex mcp add groundwork -- npx -y groundwork-mcp

Or add it to ~/.codex/config.toml by hand:

[mcp_servers.groundwork]
command = "npx"
args = ["-y", "groundwork-mcp"]

To teach Codex when to use it, copy the skill into your repo:

mkdir -p .agents/skills/groundwork
curl -fsSL https://raw.githubusercontent.com/IdeatorlabsAB/groundwork/main/skills/groundwork/SKILL.md -o .agents/skills/groundwork/SKILL.md

Start codex in your project folder, so Groundwork finds the project.

Then

Talk to your agent as you normally would:

Here are my notes from three customer interviews. Log the pains as insights.

Draft a hypothesis from the onboarding insights, with a success metric.

The pilot finished: activation went from 38% to 61%, support tickets stayed at 11 a week. Record it and write up the finding.

Why are we building the guided import?

Groundwork writes files like groundwork/insights/INS-0001-setup-takes-too-long.md. Commit them like any other file.

Related MCP server: accreta

The CLI

npx -p groundwork-mcp groundwork init        # create groundwork/config.yml
npx -p groundwork-mcp groundwork validate    # check every item and link; exits 1 on errors
npx -p groundwork-mcp groundwork trace REQ-0002
npx -p groundwork-mcp groundwork list hypothesis
npx -p groundwork-mcp groundwork import --to <web app>   # see "Groundwork for teams"

trace shows the chain behind an item (from examples/acme):

REQ-0002 Guided CSV import (solution, approved)
├─ finding FND-0001 Guided import lifts activation
│  ├─ experiment EXP-0001 Guided import pilot (completed, validated)
│  │  └─ hypothesis HYP-0001 Guided import (validated)
│  │     ├─ insight INS-0001 Setup takes too long
│  │     └─ insight INS-0002 Import errors are unclear
│  ├─ hypothesis HYP-0001 Guided import (validated) (shown above)
│  └─ insight INS-0001 Setup takes too long (shown above)
└─ requirement REQ-0001 Get set up without help (stakeholder, draft)
   └─ finding FND-0001 Guided import lifts activation (shown above)

Run validate in CI to block pull requests with broken links:

# .github/workflows/groundwork.yml
on: pull_request
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx -y -p groundwork-mcp groundwork validate

Setup

groundwork/config.yml holds your product areas, products and people (for approvals). The first write creates it if it's missing. Fill it in so agents can tag items by area and send requirements for sign-off. Agents can also add product areas and products themselves, with add_product_areas and add_products; people are always added by hand:

name: Acme
productAreas:
  - { id: onboarding, label: Onboarding }
products: [Acme app]
people:
  - { id: sam, name: Sam, role: owner, email: sam@acme.example }

Groundwork finds the project by looking for groundwork/config.yml in the current folder and the folders above it. Set GROUNDWORK_DIR to point somewhere else, and GROUNDWORK_USER to choose who you're acting as.

The full format, every field and the rules are in SPEC.md. See examples/acme for a sample project.

Tools

Read

Write

Lifecycle

get_workspace

add_insights

start_experiment

search_items

add_hypotheses

record_experiment_results

get_item

add_experiment

submit_requirement_for_approval

add_findings

approve_requirement

add_requirements

send_back_requirement

update_item, link_items

obsolete_requirement

delete_item

add_product_areas, add_products

Privacy

Insights hold what customers said, and these files usually end up in git. Groundwork tells agents to record a role ("Finance manager") and an optional reference ("P07"), never names or contact details. Check quotes before you commit them, and keep the repo private if they're sensitive.

Groundwork for teams

The Groundwork web app adds dashboards, reports, a visual evidence graph, approvals with an audit trail and Linear sync for people who don't live in a terminal. It's a separate, paid product; this project is and stays open source.

To move a project into it, create an agent token in the web app (Settings → Connect an agent), then:

export GROUNDWORK_TOKEN=gw_…
npx -p groundwork-mcp groundwork import --to https://your-groundwork-app --dry-run   # see what would happen
npx -p groundwork-mcp groundwork import --to https://your-groundwork-app

Every item keeps its links, and its original id (INS-0001) is stored with it. Running the import again skips items already there (--overwrite replaces them). Afterwards groundwork/config.yml says migrated:, so local tools only read the files and the web app is where changes go. The command prints how to point your agent at the web app's MCP server. For Codex, run codex mcp remove groundwork and add this to ~/.codex/config.toml:

[mcp_servers.groundwork]
url = "https://your-groundwork-app/api/mcp"
bearer_token_env_var = "GROUNDWORK_TOKEN"

Contributing

Issues and pull requests are welcome. See CONTRIBUTING.md.

Licence

Apache-2.0

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      An MCP server that gives LLM agents structured, safe, and traceable access to engineering project documentation stored in Markdown/Git repositories, enabling management of requirements, decisions, tests, tasks, and impact analysis.
      14
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP agents to maintain durable, evidence-aware project knowledge, retrieve precise excerpts on demand, and track decisions, conflicts, and revisions across sessions.
      1
      Apache 2.0