Skip to content
Back to search

groundwork

MarketplaceWorks with Claude CodeGitHub

Product evidence as linked Markdown files in your repo: insights, hypotheses, experiments, findings and requirements, written by your own agent over MCP.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 19 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/IdeatorlabsAB/groundwork with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/IdeatorlabsAB/groundwork'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ideatorlabsab--groundwork/badge.svg)](/listings/ideatorlabsab--groundwork)

HTML

<a href="/listings/ideatorlabsab--groundwork"><img src="/api/listings/ideatorlabsab--groundwork/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 12 lines
  1. {
  2. "name": "groundwork",
  3. "owner": { "name": "The Groundwork Authors", "url": "https://github.com/IdeatorlabsAB/groundwork" },
  4. "plugins": [
  5. {
  6. "name": "groundwork",
  7. "source": "./",
  8. "description": "Product evidence as linked files in your repo: insights, hypotheses, experiments, findings and requirements, written by your own agent.",
  9. "category": "productivity"
  10. }
  11. ]
  12. }
README.md · README · 170 lines
  1. # Groundwork
  2. **Your product evidence, in your repo, written by your own agent.**
  3. 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.
  4. ```
  5. insight ──▶ hypothesis ──▶ experiment ──▶ finding ──▶ requirement
  6. "I gave up "Guided import pilot, 10 "activation "Guided CSV
  7. after 20 will lift accounts: 61% vs 38%" import"
  8. minutes" activation" validated"
  9. ```
  10. - **No account, no API keys, no server.** Your agent does the thinking. Groundwork checks the data, keeps links valid and computes experiment verdicts.
  11. - **Plain files.** Read them, diff them, review them in pull requests, and keep them as long as you like.
  12. - **Traceability.** Ask "why are we building this?" and get the full evidence chain, or check it in CI with `groundwork validate`.
  13. ## Quickstart (2 minutes)
  14. ### Claude Code
  15. In your project folder:
  16. ```sh
  17. claude mcp add groundwork -- npx -y groundwork-mcp
  18. ```
  19. Or install the plugin, which adds the MCP server and a skill that teaches Claude when to use it:
  20. ```
  21. /plugin marketplace add IdeatorlabsAB/groundwork
  22. /plugin install groundwork@groundwork
  23. ```
  24. ### Codex
  25. ```sh
  26. codex mcp add groundwork -- npx -y groundwork-mcp
  27. ```
  28. Or add it to `~/.codex/config.toml` by hand:
  29. ```toml
  30. [mcp_servers.groundwork]
  31. command = "npx"
  32. args = ["-y", "groundwork-mcp"]
  33. ```
  34. To teach Codex when to use it, copy the skill into your repo:
  35. ```sh
  36. mkdir -p .agents/skills/groundwork
  37. curl -fsSL https://raw.githubusercontent.com/IdeatorlabsAB/groundwork/main/skills/groundwork/SKILL.md -o .agents/skills/groundwork/SKILL.md
  38. ```
  39. Start `codex` in your project folder, so Groundwork finds the project.
  40. ### Then
  41. Talk to your agent as you normally would:
  42. > Here are my notes from three customer interviews. Log the pains as insights.
  43. >
  44. > Draft a hypothesis from the onboarding insights, with a success metric.
  45. >
  46. > The pilot finished: activation went from 38% to 61%, support tickets stayed at 11 a week. Record it and write up the finding.
  47. >
  48. > Why are we building the guided import?
  49. Groundwork writes files like `groundwork/insights/INS-0001-setup-takes-too-long.md`. Commit them like any other file.
  50. ## The CLI
  51. ```sh
  52. npx -p groundwork-mcp groundwork init # create groundwork/config.yml
  53. npx -p groundwork-mcp groundwork validate # check every item and link; exits 1 on errors
  54. npx -p groundwork-mcp groundwork trace REQ-0002
  55. npx -p groundwork-mcp groundwork list hypothesis
  56. npx -p groundwork-mcp groundwork import --to <web app> # see "Groundwork for teams"
  57. ```
  58. `trace` shows the chain behind an item (from [examples/acme](examples/acme)):
  59. ```
  60. REQ-0002 Guided CSV import (solution, approved)
  61. ├─ finding FND-0001 Guided import lifts activation
  62. │ ├─ experiment EXP-0001 Guided import pilot (completed, validated)
  63. │ │ └─ hypothesis HYP-0001 Guided import (validated)
  64. │ │ ├─ insight INS-0001 Setup takes too long
  65. │ │ └─ insight INS-0002 Import errors are unclear
  66. │ ├─ hypothesis HYP-0001 Guided import (validated) (shown above)
  67. │ └─ insight INS-0001 Setup takes too long (shown above)
  68. └─ requirement REQ-0001 Get set up without help (stakeholder, draft)
  69. └─ finding FND-0001 Guided import lifts activation (shown above)
  70. ```
  71. Run `validate` in CI to block pull requests with broken links:
  72. ```yaml
  73. # .github/workflows/groundwork.yml
  74. on: pull_request
  75. jobs:
  76. validate:
  77. runs-on: ubuntu-latest
  78. steps:
  79. - uses: actions/checkout@v4
  80. - run: npx -y -p groundwork-mcp groundwork validate
  81. ```
  82. ## Setup
  83. `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:
  84. ```yaml
  85. name: Acme
  86. productAreas:
  87. - { id: onboarding, label: Onboarding }
  88. products: [Acme app]
  89. people:
  90. - { id: sam, name: Sam, role: owner, email: sam@acme.example }
  91. ```
  92. 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.
  93. The full format, every field and the rules are in [SPEC.md](SPEC.md). See [examples/acme](examples/acme) for a sample project.
  94. ## Tools
  95. | Read | Write | Lifecycle |
  96. |---|---|---|
  97. | `get_workspace` | `add_insights` | `start_experiment` |
  98. | `search_items` | `add_hypotheses` | `record_experiment_results` |
  99. | `get_item` | `add_experiment` | `submit_requirement_for_approval` |
  100. | | `add_findings` | `approve_requirement` |
  101. | | `add_requirements` | `send_back_requirement` |
  102. | | `update_item`, `link_items` | `obsolete_requirement` |
  103. | | `delete_item` | |
  104. | | `add_product_areas`, `add_products` | |
  105. ## Privacy
  106. 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.
  107. ## Groundwork for teams
  108. 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.
  109. To move a project into it, create an agent token in the web app (**Settings → Connect an agent**), then:
  110. ```sh
  111. export GROUNDWORK_TOKEN=gw_…
  112. npx -p groundwork-mcp groundwork import --to https://your-groundwork-app --dry-run # see what would happen
  113. npx -p groundwork-mcp groundwork import --to https://your-groundwork-app
  114. ```
  115. 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`:
  116. ```toml
  117. [mcp_servers.groundwork]
  118. url = "https://your-groundwork-app/api/mcp"
  119. bearer_token_env_var = "GROUNDWORK_TOKEN"
  120. ```
  121. ## Contributing
  122. Issues and pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md).
  123. ## Licence
  124. [Apache-2.0](LICENSE)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.