Set it up once. Then just say what to build.
Install · Your first feature · What you can ask for · 한국어 · 简体中文
groundwork is a Claude Code and Codex plugin that sets, once, how AI coding agents work in your repository: issue tracking, workflow, branches and releases, architecture, code review, and screen checks. After that, you ask for a feature in plain words, and the agent files the issue, implements the change, writes and runs tests, reviews it, and fixes what the reviewers find. It stops only where a person should decide.
There are no commands to learn. You can run every skill in plain words, in any language.
Claude Code:
/plugin marketplace add enebin/groundwork
/plugin install groundwork@groundwork
Then, in the repository you want to set up, say:
Set up groundwork for this repo.
Onboarding asks eight questions, recommends an answer for each, and saves your choices to GROUNDWORK.md. Every other skill reads that file.
In Claude Code, groundwork checks GitHub for a new release at most once a day and tells you once per release. To update, run claude plugin update groundwork@groundwork and restart Claude Code.
Optional: install skeptic-review to double-check review findings before they reach you. Without it, reviews show SkepticReview: OFF.
Add a sign-in screen.
That one sentence is the whole request. With the default setup, groundwork then:
- Files an issue for the request and creates a branch in its own worktree.
- Implements the change and writes tests alongside it.
- Runs your build and tests, then runs your chosen reviewers in parallel.
- Fixes confirmed findings and repeats until no serious issues remain.
- Runs screen checks on the changed screens, if enabled.
- Reports what it did and asks whether to commit.
In a repository with no commits yet, or whose build and test commands are not confirmed, groundwork first proposes a short plan that starts with a setup step, and waits for your approval.
When you are happy with it:
Push it and open a PR.
groundwork rebases, verifies again, pushes, and opens the PR. With auto-merge on, it also waits for CI, merges, and cleans up the branch.
A job too large for one PR is split into steps first; once you approve the plan, each step runs the same way.
groundwork never decides these on its own:
- Plan approval: when a large job is split into multiple steps.
- Design approval: before implementation in the
design-firstworkflow. - Pushing and opening a PR: waits until you explicitly ask.
- Merging: waits for you, unless auto-merge is on.
- Releasing: starts only when you ask, and scheduled release prep waits for your approval before publishing.
These are examples; any wording that means the same works.
| You say | What runs |
|---|---|
| "Add dark mode." / "Fix the crash on the settings screen." | step: issue → implement → test → review → fix |
| "This is big. Split it into issues." | plan, then step for each part |
| "Push it and open a PR." | takeoff, then autoland if auto-merge is on |
| "The PR is merged. Clean up." | landing |
| "Review my changes." | review |
| "Can new users get through sign-up?" | ux-journey on the running app |
| "Check the settings screen on the app." | ui-qa |
| "Release 1.2.0." | release |
| "Prepare a release every Friday." | release-prep |
| "Summarize this week." | weekly-summary |
| "I'm stopping here. Leave a note for next time." | handoff |
You can still type a skill by name, such as /groundwork:step, when you want to be exact.
Before the first question, onboarding shows every step and its recommended setup at a glance:
Each choice is a bundle: rules and skills that work together, shown with pros, cons, and token cost.
| Step | Category | Options | New project default |
|---|---|---|---|
| 1 | Language | conversation / artifacts | your language / English (saves tokens) |
| 2 | Issue tracker | local files, GitHub Projects, Linear, Jira | local files |
| 3 | Workflow | step-loop, design-first, tdd-loop, quick, review-only; worktree per issue | step-loop, worktree per issue |
| 4 | Release strategy | develop + release, main only; merge style | develop + release |
| 5 | Architecture | unidirectional, mvvm, layered-service, layered-web, none | recommended based on stack |
| 6 | Review | app, sdk, service, product, light | recommended based on project type |
| 7 | Screen checks | UX (from code or on app) and QA: every PR, before release, or manual | UX: every PR, from the code. QA: manual |
| 8 | Custom rules | free text | none |
It works best on a fresh git init, such as a side project, a hackathon prototype, or an assignment due tomorrow, so you start with rules, reviews, and QA in place. On an existing repository, it asks the same questions and recommends answers from your code.
Commit GROUNDWORK.md and the docs onboarding writes. Teammates only need to install the plugin to work under the same rules. To change a setting later, just ask; to pick up new features after a plugin update, say "update groundwork".
- Tests are part of implementation, not an option. Onboarding finds your build and test commands and writes the implementation rules into
AGENTS.md. - Reviewers for architecture, code quality, security, writing, and developer experience run in parallel on each change. Confirmed findings go to a
fixeragent in a fresh context, so your conversation receives only a short summary. - Screen checks test whether each user persona can finish its tasks, from the code or on the running app, and check the rendered UI against requirements. See screen checks and how the UX checks compare. In a benchmark, the code-based UX review found 36 of 39 seeded defects at about a tenth of the app-based review's cost.
- Thoroughness is controlled by a single preset—
eco,normal(default), orsport—that sets verification depth, review rounds, and screen-check scope together. Say "use sport mode for this one" to change it for a single request.
A review does not replace your own judgment, and checks on the running app can take a long time and many tokens.
Nothing here runs until you ask. Say "show me the groundwork add-ons" to browse them.
| Add-on | What it does |
|---|---|
slack-report |
Sends work changes and test results to Slack |
handoff |
Saves what is done, what is left, and where to start next |
weekly-summary |
Summarizes a week's commits, PRs, and issues |
release-notes |
Turns a range of commits into user-facing release notes |
ux-journey |
Has a first-time user walk a whole journey on the running app and reports where they get stuck |
release-prep |
Prepares and verifies releases on a schedule, then asks for final approval |
Slack credentials stay outside Git in ~/.config/slack-report/; see Slack setup. Turning on automatic Slack reports installs repository-local Stop hooks for both clients.
All skills
| Skill | Description |
|---|---|
onboarding |
Initialize or update GROUNDWORK.md |
update |
After a plugin update, apply migrations and pick new features from the release notes |
addons |
Browse optional features and continue their setup or one-off use |
plan |
Break a large task into a parent issue and smaller step issues |
step |
Run a single step: implement, then loop through verify → review → fix until no confirmed 🔴/🟠 issues remain |
takeoff |
Rebase, push, and open the PR for a finished step |
landing, rejoin |
Clean up after a merge, or move a branch out of its worktree |
release, autoland |
Cut a release, and merge once CI passes |
review-and-fix, commit-push |
The quick workflow |
review |
Run the selected reviewers in parallel and combine their findings |
ux-review |
Usability review from chosen user personas, from the code or on the app |
ui-qa |
Launch the app to check UI behavior automated tests can't cover |
slack-report, handoff, weekly-summary, release-notes, release-prep, ux-journey |
Optional add-ons; see above |
The full specification is in plugins/groundwork/reference/config.md. Keys are only ever added, never renamed or removed. When the structure must change, the schema version is bumped and onboarding migrates your file.
MIT