# Groundwork

A Claude Code plugin that plans product and design decisions — a visual picker, EARS requirements, design tokens — into a handoff-ready spec for build-loop.

Status: planned

## The Problem

The common failure mode is skipping straight from idea to code: open build-loop, describe the feature, and let the agent fill in every product and design decision that hasn't actually been made yet. The plans that come out are plausible, not deliberate — because nobody decided the personas, the acceptance criteria, the data model, or what the interface should actually look like before the agent started writing.

## Approach

Groundwork is the step that gets skipped: settle the product and the design first, then hand off. It routes a single command, `/groundwork:run`, to one of its modes based on what's asked for — discovering a design direction through a visual picker, comparing full-screen mockups, or turning an idea into a written spec. There's no separate command to remember and no flag to pick a mode.

The visual picker narrows by letting the user click between concrete option previews — platform, nav, color, type, density, motion — rather than answering an open-ended interview. A confidence/info-gain convergence gate (confidence ≥0.80, info-gain <0.25) decides on its own when enough has been picked, so the session has a defined stopping point instead of running until someone gets bored.

## How It Works

```text
$ /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 build
```

`requirements.md` and `design.md` carry EARS-shaped acceptance criteria, a data model, API contracts, and component architecture — decisions written so a builder can act on them without guessing. `traceability.json` chains Need → Feature → Screen → Task → Test, so every task in the spec set traces back to the requirement it satisfies. Ideation starts under `~/dev/designs/<slug>/` and graduates into the target repo's `.designdoc/` once it becomes a real project.

## Architecture

A Claude Code and Codex plugin (TypeScript, Python) with one entry command per host and internal routing to its four flows. It reads a one-line description to start the visual picker — a written spec is optional context, not a prerequisite. Groundwork mines ProductPilot and the published ui-guidance plugin as reference material but never modifies either; there's no shared runtime between them.

## Boundaries

Groundwork plans; it does not build. `build-request.json` carries the contract build-loop validates at Phase 1, and the handoff stops there — build-loop (or any builder that reads the output) does the actual building. It also carries no baked-in LLM API key or hosted service: the host agent already running is the LLM.

## Results

⚠️ pre-release — no benchmark yet. Groundwork is at v0.3.0 in a private repo, actively being built, with no public install or download at this stage. What's documented above is the routing, the convergence gate, and the spec-set shape — not a measured outcome.

## Lessons

The convergence gate and the handoff boundary are the two decisions the design centers on: a picker with no defined stopping point turns into an open-ended interview, and a planning tool that quietly starts writing code stops being a planning tool.

## Links

- [HTML project page](https://rosslabs.ai/projects/groundwork/)