Groundwork

Open source

Groundwork for Claude Code

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

groundwork-mcp 0.3.0 · Apache-2.0

Evidence that lives next to your code

An MCP server and CLI. Claude Code, or any MCP agent, keeps customer insights, hypotheses, experiments, findings and requirements as linked Markdown files in a groundwork/ folder in your repo. Every requirement traces back to the findings, experiments and customer quotes behind it.

Why files in your repo

No account, no API keys, no server

Your own agent does the thinking. Groundwork checks the data, keeps links valid and computes experiment verdicts. An experiment is validated only if the primary metric hits its target and no guardrail is breached.

Plain files

Readable, diffable and reviewable in pull requests. Kept 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

In a project folder, add the MCP server to Claude Code.

Add the MCP server
claude mcp add groundwork -- npx -y groundwork-mcp

Or install it as a Claude Code plugin. That adds the MCP server plus a skill.

Or as a plugin, inside Claude Code
/plugin marketplace add IdeatorlabsAB/groundwork
/plugin install groundwork@groundwork

Other agents

Groundwork works with any MCP agent. The server command is npx -y groundwork-mcp.

Codex

Add the MCP server
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.

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

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

Then talk to your agent normally

  • “Here are my notes from three customer interviews. Log the pains as insights.”
  • “Why are we building the guided import?”

Files look like groundwork/insights/INS-0001-setup-takes-too-long.md

From a customer's words to a requirement

Insight, hypothesis, experiment, finding, requirement. Each one links to the one before.

  1. Insight“I gave up after 20 minutes”
  2. HypothesisGuided import will lift activation
  3. ExperimentPilot with 10 accounts, validated
  4. FindingActivation 61% vs 38%
  5. RequirementGuided CSV import

Run groundwork trace REQ-0002 to see a requirement's evidence tree in your terminal.

The CLI and the MCP tools

CLI

Run with npx -p groundwork-mcp groundwork <command>, or install it with npm i -g groundwork-mcp.

groundwork init
Create groundwork/config.yml
groundwork validate
Check every item and link. Exits 1 on errors, for CI
groundwork trace REQ-0002
Show the evidence chain behind an item
groundwork list [kind]
List items, optionally only one kind
groundwork import --to <web app URL>
Move a project into the web app. Add --dry-run to check first
groundwork mcp
Run the MCP server (same as groundwork-mcp)

MCP tools

Read

  • get_workspace
  • search_items
  • get_item

Write

  • add_insights
  • add_hypotheses
  • add_experiment
  • add_findings
  • add_requirements
  • update_item
  • link_items
  • delete_item
  • add_product_areas
  • add_products

Lifecycle

  • start_experiment
  • record_experiment_results
  • submit_requirement_for_approval
  • approve_requirement
  • send_back_requirement
  • obsolete_requirement

Privacy

Agents are told to record a role, like “Finance manager”, and an optional reference, like “P07”. Never names or contact details. Files usually end up in git, so check quotes before you commit them, and keep the repo private if they're sensitive.

When your team wants more

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.

The open-source project is and stays open source. To move a project into the web app:

  1. Create a token

    Sign in to the web app and open the workspace you want to import into. Go to Settings → Connect an agent and create a token. The token belongs to that workspace, so that's where the import goes. Copy it straight away: it's shown only once, and starts with gw_. You need to be an editor or owner.

  2. Check what would be imported

    In your project folder, set the token and do a dry run. It shows which workspace the items will go to and how many are new. Nothing is saved.

    Dry run
    export GROUNDWORK_TOKEN=gw_…
    npx -p groundwork-mcp groundwork import \
      --to https://groundwork.ideatorlabs.com --dry-run
  3. Import

    Run it in the same terminal, so the token is still set.

    Move the project into the web app
    npx -p groundwork-mcp groundwork import \
      --to https://groundwork.ideatorlabs.com

Items keep their links and their original ids, like INS-0001. Running it again skips items already there; add --overwrite to replace them. Afterwards groundwork/config.yml says migrated:, so local tools only read the files, and the command prints how to point Claude Code or Codex at the web app.

Contribute

Issues and pull requests are welcome.