groundwork-scaffold-interface

Reads application code and generates a draft docs/specs/SPEC-INTERFACE.md for the dev to review and approve.

This is the only skill in the groundwork suite that is allowed to read application code (src/, app/, lib/, etc.). The output is a draft — the dev owns the final version.

When to use

docs/specs/SPEC-INTERFACE.md does not exist and the dev wants to bootstrap it
SPEC-INTERFACE.md exists but is missing sections (auth flow, UI structure, new endpoints)
Before running /groundwork verify for the first time on a project
The dev asks to scaffold or generate the interface contract

When NOT to use

SPEC-INTERFACE.md already exists and is complete — use /groundwork verify directly
The dev wants to write SPEC-INTERFACE.md manually from scratch
You are inside /groundwork verify — that skill must never read application code

Command

`/groundwork scaffold-interface`

Scans the codebase and generates a draft docs/specs/SPEC-INTERFACE.md.

Step 1 — Detect interface type

Scan for:

REST/API: Route files (routes/, api/, controllers/), framework patterns (Express app.get, Fastify, Hono, Next.js API routes, etc.)
Web: Frontend entry points (pages/, app/, components/), framework patterns (React, Vue, Svelte, Next.js pages, etc.)
CLI: Binary entry points, commander/yargs/meow usage

Set Type to rest, web, rest+web, or cli.

Step 2 — Extract base URLs

Look for:

Environment variables (PORT, BASE_URL, API_URL, VITE_*)
Server startup code (listen port)
Dev server config (vite.config, next.config, etc.)
Proxy configurations

Step 3 — Extract auth

Look for:

Auth middleware, passport config, JWT/session setup
Login routes/pages
Token storage patterns (cookie, localStorage, header)

Build the Auth and Auth flow sections:

## Auth
type: bearer | cookie | none
token_env: TEST_AUTH_TOKEN

## Auth flow
web:
  page: /login
  fields:
    - email → input
    - password → input
  submit: click "Sign in" button
  result: session cookie set, redirects to /dashboard
api:
  endpoint: POST /auth/login
  body: { email, password }
  result: 200 { token }

Step 4 — Extract endpoint map

Scan route definitions and build:

## Endpoint map
POST /auth/login         → 200 {token} | 401
GET  /users/:id          → 200 {user} | 404
POST /orders             → 201 {order} | 422

For each route, determine: HTTP method, path, success response (status + shape), error responses.

Step 5 — Extract web entry points and UI structure

For web/rest+web projects, scan pages/components to build:

## Web entry points
login     → /login
dashboard → /dashboard
checkout  → /checkout

## UI structure
/login:
  - email input
  - password input
  - submit button
  - error message (visible on auth failure)

/checkout:
  - cart items list
  - card number input
  - submit button ("Place order")
  - order confirmation (visible on success)
  - payment error message (visible on failure)

For UI structure, identify:

Form inputs — text fields, selects, checkboxes
Action elements — buttons, links that trigger behavior
State elements — messages, containers that appear/disappear based on state (errors, success, empty states, loading)

Focus on elements that a BDD scenario would interact with or assert on. Skip purely decorative elements.

Step 6 — Generate draft

Write docs/specs/SPEC-INTERFACE.md using exactly the section format below. This format is required by groundwork-verify — do not invent a different structure.

Mark uncertain items with # TODO: verify comments inline.

# Interface Contract — DRAFT

> ⚠️ DRAFT generated by /groundwork scaffold-interface.
> Review every section. Correct anything that describes current behavior instead of intended behavior.
> Items marked "# TODO: verify" need your confirmation.

## Type
rest+web

## Base URLs
api: http://localhost:3000/api/v1
web: http://localhost:5173

## Auth
type: bearer
token_env: TEST_AUTH_TOKEN    # TODO: verify env var name

## Auth flow
web:
  page: /login
  fields:
    - email → input
    - password → input
  submit: click "Sign in" button
  result: session cookie set, redirects to /dashboard  # TODO: verify redirect
api:
  endpoint: POST /auth/login
  body: { email, password }
  result: 200 { token }

## Endpoint map
POST /auth/login         → 200 {token} | 401
POST /auth/register      → 201 {user} | 422
GET  /orders             → 200 [{order}]
POST /orders             → 201 {order} | 422
GET  /orders/:id         → 200 {order} | 404

## Web entry points
login     → /login
dashboard → /dashboard
checkout  → /checkout

## UI structure
/login:
  - email input
  - password input
  - submit button ("Sign in")
  - error message (visible on auth failure)

/dashboard:
  - recent orders table (columns: id, date, status, total)
  - "New order" button

/checkout:
  - cart items list
  - cart total
  - empty cart message (visible when cart is empty)   # TODO: verify
  - card number input
  - card expiry input
  - card cvc input
  - payment form container
  - submit button ("Pay now")
  - order confirmation with order number (visible on success)
  - payment error message (visible on payment failure)

## Notes
Checkout is a multi-step flow: step 1 cart review, step 2 payment.
# TODO: verify if retry is possible after payment error

The section headers (## Type, ## Base URLs, ## Auth, ## Auth flow, ## Endpoint map, ## Web entry points, ## UI structure, ## Notes) are mandatory and must use these exact names. groundwork-verify parses them.

Output

After generating, present the draft to the dev:

Generated DRAFT docs/specs/SPEC-INTERFACE.md

Detected:
  Type: rest+web
  Base URLs: api http://localhost:3000/api/v1, web http://localhost:5173
  Auth: bearer token via POST /auth/login
  Endpoints: 8 routes mapped
  Web pages: 4 pages with UI structure

⚠️  This is a DRAFT. Review it carefully before running /groundwork verify.
Items marked with "# TODO: verify" need your confirmation.

The purpose of SPEC-INTERFACE.md is to describe the CONTRACT, not the implementation.
If the code has bugs, the contract should describe the intended behavior, not the current behavior.
Edit anything that describes "what the code does" instead of "what the code should do".

After review, rename the heading from "# Interface Contract — DRAFT" to "# Interface Contract"
and remove the DRAFT warning block.

Critical reminder

This skill exists to save the dev time bootstrapping SPEC-INTERFACE.md. It does NOT replace the dev's judgment. The draft is a starting point — the dev must review every line because:

Code may have bugs that shouldn't become part of the contract
Route definitions may not reflect intended behavior
UI elements may be incomplete or in flux

The dev's review is what breaks the bias cycle. Without it, this skill would just launder implementation details into the spec.

Common mistakes

Mistake	Fix
Generating and auto-approving without dev review	Always present as DRAFT, always ask for review
Including implementation details (function names, internal state)	Only external interface: URLs, HTTP methods, UI elements
Describing current behavior instead of intended behavior	Mark uncertain items with `# TODO: verify`
Missing error states and empty states in UI structure	Always include: error messages, empty states, loading states, success confirmations
Forgetting auth flow details	Auth flow is critical — include page, fields, submit action, and result