ProvenMap
Use Cases
On this page

Build a New App from a Spec

This walkthrough turns a written product spec into a landscape on your root board, an app board with a target sketch, and sequenced work items. The first work item is built in a new repo and Completed. The architect works in the workspace plugin and the developer in the code plugin. In the example below, each session took about 40 minutes.

The example is Volleyland, a multiplayer learning game for school students: a Next.js web client and a NestJS game server in one monorepo, on Supabase. Its spec is a 6,600-word markdown document with a stack, a repo layout and delivery phases. Your spec needs none of those headings, but every decision it settles is a question the plugins don't have to ask you.

Before you start

  • An empty workspace. /setup runs only on an empty root board; on a populated one, start at Turn a planned system into an app.
  • The workspace plugin signed in with a Read + write token, on Claude Code or Codex.
  • The code plugin, installed where the developer works (Claude Code, Codex or Cursor).
  • The spec as a file you can add to the architect's session.
  • An empty folder for the repo, with git. Claiming a work item reads the current branch, which must match the branch the binding governs (main here).

Found the landscape from the spec

Run /setup. When it asks whether you are mapping systems that exist or founding something new, choose to found something new. Found mode draws the systems you intend to build at the product level and creates no app boards or bindings, because there is no code yet.

Add the spec instead of answering

The plugin asks four questions: the one-liner, the intended systems, the actors and external services, and any zones. Add the spec to the session and say it has the answers. The plugin reads it, then asks only what the spec leaves open. For Volleyland, that was whether anyone is coding yet, whether an optional cache belongs on the landscape, and whether the spec's six roles appear as six actors or four groups.

Approve the plan

You review a landscape sketch and a table of systems with their kind, archetype and container. Every system is planned or SaaS. Volleyland's plan was 2 containers, 10 nodes and 11 edges. The web and server sit in a VPS zone behind a reverse proxy, and Supabase Auth and PostgreSQL in a managed zone, beside media storage and four actor groups.

Commit it

The plugin styles the landscape, shows what the commit will land, and asks for a one-line reason. One commit saves the landscape and the root board's description.

To change what you committed, say so after the Outcome. The Volleyland architect wanted one monorepo instead of two systems. The plugin replaced the web and server nodes with one volleyland node, moved their edges to it and committed the change.

Turn a planned system into an app

Run /new-app <node> on the planned system, here /new-app volleyland. One round of questions settles how the app enters the build. The plugin words them for your spec; these are what they decide:

QuestionVolleyland's answerWhat it decides
Where does the repo stand?Bind now; the repo is comingBinds the app as a new app: the board is the target and the code catches up. If code already exists, it binds an existing app instead, and the first push fills the board. You can also leave the binding for later.
Which branch does the binding govern?mainThe branch whose pushes become the board's truth.
How deep is the target sketch?The apps plus the components the spec namesHow much the plugin draws before any code exists. Volleyland's other choices were the apps and packages only, or every server module.
What does the first work item ask for?The spec's Phase 0 prototypeThe founding work item, drafted from the spec's first delivery phase with its exit condition.

The plugin then gives the node an app archetype, creates its app board and draws the target sketch on it. Volleyland's has 19 elements and 25 edges, in apps/web, apps/server and packages/. After you commit the sketch, the plugin binds the board to the repo. It then reads the founding work item back to you, with an anchor and a note for each element it changes. You approve it, and it lands as a Draft.

Prepare the build

/new-app ends by asking Prep the build now? Answer Now, or run /prepare-app volleyland later. Either way it measures the app against App readiness, three conditions read from the board each time:

TEXT
- [x] Founding work item landed (1 work item(s) on the board)
- [ ] Spec set authored (0 sequenced)
- [ ] Skills configured (0 enabled)

Sequence the rest of the work

The plugin proposes the remaining work as work items, each with the spec's own exit condition and the work items it waits for. Volleyland's became Phases 1 to 4 under a new Volleyland MVP epic, with Phases 2 and 3 running side by side after Phase 1. You approve the read-back, and each lands as a Draft.

Choose the compiled skills

The plugin reads the skill library for the app's stack and proposes a set. Volleyland's had 8 of 58, including TypeScript, Supabase, Playwright, performance and DevOps skills. Some take settings, such as the CI platform; the performance skill carried the spec's budgets. Enabling them applies at once, outside the working copy.

When all three conditions hold, the check reads Ready to build and lists the work items in build order.

Hand off the work items

Developers can't pull a Draft. Open the app board's Work items screen, select the drafts, and hand them off from the bulk bar. Each one becomes Open and visible to /work-items pulls. Hand it off covers who can hand off whose work items.

Build the first work item

The developer starts in the empty repo. Nothing in the repo is edited until they approve a plan.

Sign in

Run /login and pick the volleyland board. The Outcome confirms the board and branch, and suggests building from compiled skills, since the repo is empty.

Run /build

/build reads the app's build context: the compiled skills, the open work items, the 19 unbuilt elements of the sketch, and any aspect contracts. If the compiled skills aren't in the repo yet, it writes them first; Volleyland's arrived as 90 files under .claude/. It then proposes a plan and asks how far to go. Volleyland's developer chose the scaffold plus Phase 0.

Approve the work item's plan

/build claims the work item, so it shows In progress under your name. Before any edit, it compares the work item with the code in a gap review and rates the gap clean, minor or blocking. It then plans each element in a folder named after it, so the next sync can match them. Approve the plan, change it, or send the work item back to the architect.

Verify and resolve

/build implements the plan, runs the project's own checks and records each result on the work item. You decide how to close. Volleyland's developer committed the code and resolved Phase 0 with a note. The note names the two parts still left for a person: the VPS deploy and the frame-rate measurement on a school laptop.

Note

Recorded checks stay valid for about 30 minutes. Resolve while they are fresh, or run the checks again.

Check it worked

  • The root board holds the landscape, and the app's node opens its app board.
  • On the Work items screen, the first work item is Completed, with the developer's note and commit. The rest are Open, in the order the plan set.
  • The app board's Bindings card shows the binding's last push.
  • The repo holds the code, the compiled skills under .claude/skills/ and pmap-skills.lock.json. Commit the last two so the team shares them.

Then run /analyze and /sync. They map the new code onto the app board, which still shows every element of the sketch as unbuilt, and the plugin compares the code with the target sketch. Run /build again for the next work item.

What's next

Work items

Statuses, the build order on the grid, epics, and how developers resolve work.

The Workspace Plugin

Every workspace plugin command, including /new-app and /prepare-app.

The Code Plugin

/skills, /build and /work-items, and how the next sync maps what was built.

Skills & Recipes

What a compiled skill carries, and how it reaches the repo.