Formative

Discover what your app needs by talking it through—and trying it.

Start with a vague app or website idea. Formative interviews you persistently, follows decisions into their consequences, proposes overlooked requirements, and uses interactive frontend prototypes when seeing an interface helps you decide. The result is a product plan shaped by what you actually want.

Quick start · Install for your agent · Discovery workflow · Read the skill · Component design · Contributing

What is included

The interview adapts Matt Pocock's grilling and domain-modeling methods, with pinned attribution and the original MIT notice. You do not need Grill Me installed.

Quick start

Use Node.js 24+. For Pi, install the package directly:

pi install npm:@koboimomo/formative

Run /reload, then /formative in your project. The package includes the extension and skill.

For Claude Code or Codex:

npm install -g @koboimomo/formative

# Claude Code
formative install-skill --agent claude
claude mcp add --scope user --transport stdio formative -- formative mcp

# Or Codex
formative install-skill --agent codex
codex mcp add formative -- formative mcp

Restart the agent, then invoke /formative in Claude Code or $formative in Codex. Install only the integration you use. The npm package includes built browser assets; no build step or Pi installation is required for Claude Code or Codex. Installation, updates, and source setup.

Try the fictional demo

After the npm installation:

formative init --project .local/demo --fixture workspace
formative preview --project .local/demo --manual

Open the printed URL and keep the terminal running. Manual mode saves feedback but does not generate revisions itself. Finish prototype testing saves the checkpoint and stops the server. Reopen with preview; do not initialize the same project twice.

Choose your agent

Claude Code and Codex do not require Pi. The MCP server runs no model; the host agent processes feedback with its own tools and account. A worker must actively call wait to receive notes. If your host cannot keep a background worker active, feedback stays queued until an agent handles it—there is no universal idle-host wakeup. Feedback and recovery

Interview → prototype → learn → continue

flowchart LR
  A[Vague idea] --> B[Questions and requirement map]
  B --> C[Prototype an open question]
  C --> D[Try it and send feedback]
  D --> B
  B --> E[Agent-authored product plan]

1. Describe the idea. The agent maps major journeys, recommends choices, and explores missing behavior.
2. Follow the questions. Unknown, blocked, rejected, and explicitly deferred branches stay visible.
3. Try a prototype when it can answer a question. Ordinary clicks use local mock state; they do not call a model.
4. Send feedback. The worker updates the relevant prototype and behavioral requirements, preserving decisions and revision checks.
5. Finish that checkpoint. Return to the interview with what you learned; closing a preview does not finalize the plan.
6. Ask for the plan when ready. The agent writes a structure suited to the product, including unresolved issues if you requested an early draft.

A prototype is a requirements rehearsal

Simulated login, payment, and saving are not real services. Prototype colors, typography, component choices, mock values, and layout do not prescribe the final implementation. You choose final design separately using your references and direction.

Generated snapshots live under .formative/exports/. They contain product records represented in the prototype, not every discovery note. The agent combines those records with the interview and unprototyped requirements to write plan.md or your chosen destination. Runtime exports never overwrite that written plan. Applied feedback is not blanket approval.

Project state, revision snapshots, feedback, and checkpoint handoffs live in the selected project's .formative/ directory. Back it up with your project. The browser runs locally; feedback processed by an agent follows its provider's policy. Security and data boundaries

A coherent catalog, with room to extend

Components share typography, spacing, control geometry, states, and focus behavior. Specs use semantic variants rather than arbitrary CSS or executable HTML. Search the catalog and retrieve only the contracts you need:

formative catalog --query form
formative catalog --name Input

Project-local components can extend the catalog through a TSX implementation and validated manifest. They are trusted developer code, not an untrusted plugin sandbox. A catalog limitation must remain a prototype limitation; it must not silently remove a product requirement. Component authoring

Use it with Planboard

Planboard provides a separate browser workspace for reviewing plans, diagrams, annotations, and approved versions. Finish discovery in Formative, then take the written plan into Planboard if useful. Either works independently.

Development and limits

From a source checkout:

npm test
npm run catalog:check
npm run build
npx playwright install chromium
npm run test:browser
npm run check:release

Tests exercise validation, revision conflicts, worker lifecycle, Pi adapters, MCP feedback/disconnects, and browser behavior using temporary projects and fake workers. They do not make paid model calls or establish identical interview quality across models. CI is configured for Linux; macOS and Windows commands are provided but not yet end-to-end tested.

This is an early public release. The catalog cannot express every possible interface, simulations are not production backends, and a detached CLI cannot wake an idle agent. Agent behavior still depends on the host and model. Architecture · Third-party credits

License: MIT, with the bundled upstream skill attribution and third-party licenses preserved.