Installation
Groundwork needs Node.js 22 or later. Check with node --version; if it's older, install a
current version first. (The markdown core works in any tool that reads files; Node is only needed
for the CLI.)
| System | Command |
|---|---|
| Windows | winget install OpenJS.NodeJS.LTS |
| macOS | brew install node |
| Linux | nvm install --lts with nvm |
Add Groundwork to a project
In your project's folder, run:
npx groundwork-ai initIt asks which AI tool you use:
- Claude Code
- OpenCode
- None: plain markdown, works with any tool
It works in a new, empty folder or in a project that already has code. Existing CLAUDE.md and
AGENTS.md files are never replaced — Groundwork appends its pointer lines and leaves everything
else alone.
You can skip the question with a flag, and preview first:
npx groundwork-ai init --adapter opencode
npx groundwork-ai init --dry-run # show what would change, write nothing
Start working
Open your AI tool in the project and type /gw.
- Claude Code and OpenCode get native commands.
/gwis the one to remember. - Plain markdown: ask your agent to "read
.groundwork/commands/gw.mdand follow it".
The first time, /gw runs setup: a few questions about the project (name, one sentence on what it
does), whether you already chose a stack, how much explanation you want, and whether you want to
approve every piece of work or each milestone. Then it writes your AGENTS.md, config and spec
starter, and tells you the next step.
Works on existing code
Bringing an existing repo under Groundwork? Setup reads the manifest, tests, CI and git history, maps the codebase, records what's already in use as decisions, and saves a test baseline so old failures don't block new work. Existing projects →
What init writes
| Path | What it is |
|---|---|
AGENTS.md | The short page your agent reads every session. Points at everything else. |
.groundwork/ | The project's state and the agent's playbook: spec, cards, roles, commands, workflow, lessons, evidence, guards. |
.claude/ or .opencode/ | Adapter files: commands, subagents, hooks. Plain markdown installs none. |
Updating
npx groundwork-ai upgrade # refresh roles, commands, workflow, guards, hooks
npx groundwork-ai doctor # check the install and the context budgetupgrade refreshes Groundwork's own files and asks before overwriting anything. Your spec, cards,
decisions, handoff, lessons and evidence are never touched. doctor tells you when a project is
behind the CLI and what to fix.