You ask the agent to build something and it starts writing code before anyone's agreed what "done" looks like.
Route the request, converge on a decision, and publish a spec a builder can execute.
Groundwork picks the flow from a plain-language request, stops asking once answers stop moving the decision, and publishes an artifact set build-loop validates before it runs.
Claude Code & Codex plugin · v0.3.0 · private repo · in active development
$ /groundwork:run help me figure out the design
● routing → explore-ui (visual picker, not a terminal Q&A)
narrows across platform → nav → color → type → density → motion
convergence gate (confidence ≥0.80, info-gain <0.25) → design-tokens.md
$ /groundwork:run spec this idea
● routing → design (structured written spec)
emits 13 artifacts, published atomically under one manifest
build-request.json is what build-loop validates — handoff, not a buildProduct walkthroughs
See it at work
You never pick a mode
`/groundwork:run` reads the request and routes it — discover a design direction, compare full-screen mockups, or turn an idea into a written spec. No flags, no separate commands to remember.
You click between real options, not fill out a form
The visual picker shows concrete option previews and records what you pick — platform, nav, color, type, density, motion — then converges on its own. A confidence/info-gain gate decides when to stop, so it never turns into an open-ended interview.
Requirements with acceptance criteria, not a wall of prose
`requirements.md` and `design.md` carry EARS-shaped acceptance criteria, a data model, API contracts, and component architecture — decisions a builder can act on without guessing.
It stops at the spec set
The engine publishes 13 artifacts in one atomic transaction, with `artifact-manifest.json` written exactly once and last so a half-written set cannot be observed. `build-request.json` carries the contract build-loop validates at Phase 1; `traceability.json` chains Need → Feature → Screen → Task → Test. Groundwork ends there — build-loop does the building.
- Not a builder — output ends at a handoff-ready spec set for build-loop; it never writes application code
- No baked-in LLM API key or hosted service — the host agent you're already running is the LLM
- Never modifies ProductPilot or the published ui-guidance plugin — it mines them as reference only, no shared runtime
Does Groundwork build the app?
No. It plans the product and the design and stops at a spec set — build-loop (or any builder that reads its output) does the actual building.
Do I need a written spec before I can use the visual picker?
No. The picker works from a one-line description of what you're designing; a Spec is optional context, not a prerequisite.
Where does the design work live?
Ideation starts under `~/dev/designs/<slug>/` and graduates into the target repo's `.designdoc/` once it becomes a real project.
Can I install it yet?
Not yet. It's at v0.3.0 in a private repo, actively being built — no public install or download at this stage.
I kept skipping straight from idea to code — open build-loop, describe the feature, and let the agent fill in every product and design decision I hadn’t actually made yet. The plans that came out were plausible, not deliberate.
Groundwork is the step I was missing: get the product and the design settled — personas, acceptance criteria, a data model, a real design-token system — before build-loop ever opens a file. It doesn’t build anything itself. It stops at a spec set build-loop can read natively, so the decisions stay mine and the execution stays fast.
Claude Code & Codex plugin · v0.3.0 · private repo · in active development