Groundwork

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

$ /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 steering.md · requirements.md · design.md · tasks.md · traceability.json
  tasks.md is build-loop's native plan format — 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 plugin (TypeScript, Python) with one entry command and internal routing to its three modes. 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. tasks.md emits build-loop’s native plan format 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 a v0.1.0 scaffold 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.