groundwork
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.
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
Markdown
[](/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
- {
- "name": "groundwork",
- "owner": { "name": "The Groundwork Authors", "url": "https://github.com/IdeatorlabsAB/groundwork" },
- "plugins": [
- {
- "name": "groundwork",
- "source": "./",
- "description": "Product evidence as linked files in your repo: insights, hypotheses, experiments, findings and requirements, written by your own agent.",
- "category": "productivity"
- }
- ]
- }
README.md · README · 170 lines
- # 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:
- ```sh
- 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
- ```sh
- codex mcp add groundwork -- npx -y groundwork-mcp
- ```
- Or add it to `~/.codex/config.toml` by hand:
- ```toml
- [mcp_servers.groundwork]
- command = "npx"
- args = ["-y", "groundwork-mcp"]
- ```
- To teach Codex when to use it, copy the skill into your repo:
- ```sh
- 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.
- ## The CLI
- ```sh
- 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](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:
- ```yaml
- # .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:
- ```yaml
- 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](SPEC.md). See [examples/acme](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:
- ```sh
- 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`:
- ```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](CONTRIBUTING.md).
- ## Licence
- [Apache-2.0](LICENSE)
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.