pica

Describe the product you want. Get requirements your team recognises and a demo your client can use. An expert team for Claude Code, with the checking built in.

---

Start in two lines

/plugin marketplace add vqdungwork/pica
/plugin install pica@pica

Restart Claude Code, then describe what you want in your own words:

A dispensing queue for our four pharmacies. Staff lose an hour a day finding where a prescription is. Assembly and the final check have to be two different people.

That is enough to start. It asks for what it cannot derive, shows you three things as it goes, and stops three times: once for the engagement scope, once for the design system, and once at the end for the PRD, the scope of work and the demo together.

What you get

You want	You say	You get back
The whole engagement	here is the brief	a PRD your team recognises, an agreed scope of work, and demo.html: a React demo your client can actually click, at every screen size and every state, with everything it had to assume listed beside it
A design file too	and port it to Figma	the above, plus a Figma file checked frame by frame against the capture

Both are finished pieces of work, not truncated ones. Figma is optional and you can skip it.

pica stops at the demo. What it costs to build from there is your estimate to make: pica gives you the requirements, the scope and a working thing to price against, and does not price it for you.

What pica does for you

It	What that means
Understands the work	Turns your paragraph into requirements your team recognises: what happens today, what changes, the rules, and a document a non-technical reader can follow
Knows your industry	28 of them. Who can say no, which colours already mean something, what the field treats as a mistake no matter what you asked for
Shows you structure first	Greyscale layout before anything is styled, so the conversation is about what goes where while that is still cheap to change
Checks it before you see it	251 automated checks: contrast, coverage, the words, the wiring. Nothing reaches you having only been looked at
Has it reviewed by others	Three to five independent reviewers, none of them seeing each other's findings
Knows who will use it	Not just the industry: the age band, the region, the conditions of use. Older users set a floor on type size and contrast that no amount of sector convention gets to go under
Gives you something to click	A React demo with mock data, served at a URL, where every state has its own link. Not a picture of a product
Proves it back to you	Measured against your original brief, never against a plan that drifted on the way

---

It already knows your industry

An education product built like a bank's admin panel passes every technical check. A teacher spots it in a second. pica carries what each field already settled, so you are not paying to rediscover it.

Banking and payments  ·  Insurance  ·  Healthcare  ·  Pharmacy  ·  Education  ·  Legal  ·  Retail and e-commerce  ·  Food and hospitality  ·  Logistics and delivery  ·  Property and rental  ·  Travel and mobility  ·  Media and publishing  ·  Manufacturing  ·  Energy and utilities  ·  Government  ·  Charity and non-profit  ·  HR and recruitment  ·  Agriculture  ·  Construction  ·  Fitness and wellness  ·  Telecoms  ·  Agencies and consultancies  ·  Developer tools  ·  Games  ·  Automotive  ·  Events and ticketing  ·  Beauty and salon  ·  Cybersecurity

For each one it knows who can veto, which colours are already taken and why, how dense the screens should be, how the product should speak, and what the field treats as a defect regardless of the brief.

This is a floor, not a template. The researcher still measures real products for your project, every time, and the design is argued from what it found. What the industry knowledge does is stop you paying to rediscover that amber means a dispensing warning, and stop you shipping something a pharmacist would reject on sight. Ten products in the same industry should share the conventions that field already settled and share nothing else, which is why the direction comes from measurement and only the constraints come from here.

Red means overdrawn in a bank and clinical emergency in a hospital. Red, amber and green on a factory floor are inherited from site signage, so using them decoratively is a safety problem rather than a taste disagreement. Blue on a food menu reads as spoilage.

If your field is not one of the 28, pica says so and stops rather than guessing. Four words that could mean two different industries are refused for the same reason.

---

The flow

Seven steps. Three stop and wait for you, and three more show you something and carry on. Or say run the whole thing and it does all seven, pausing only at the three that matter.

Step	Who	What happens	Command
1 · Intake	you	Your brief, kept word for word. What is in scope, what is out, which screen sizes it has to work on, and the field it is in	/pica
2 · Discovery	3 to 5 researchers, one per group of users	Who uses it and what actually hurts, counted rather than assumed. Who can stop the project and what they fear. What your competitors charge, and how the business itself runs	/pica-discover
3 · Research	3 to 5 researchers, none seeing another's findings	Real products in your field, measured rather than admired. The tokens come out of what was measured	none
4 · Analysis	analyst and modeller	The real problem, the process across every role, the rules, who may see what, and a requirements document your team can actually read	/pica-analyse
5 · Design	designer, writer, 3 to 5 reviewers	Structure first, then a direction chosen from three, then the design system, then every screen at every size in every state, and the words on them	/pica-wp
6 · You confirm	you	The PRD is right, the scope is agreed, and the demo does what you expect. Nothing further runs until all three are	none
7 · Handover	analyst	Proved against your original brief, not against a plan that drifted. Figma, if you want it, is ported and verified frame by frame	/pica-close
any time	you

Figma is optional and sits beside step 7, never in front of it. Where Figma and the design disagree, Figma is wrong.

Something to read first

examples/approvals/ is a complete pica project: a payment-approval surface for a retail bank, small on purpose and complete on purpose. Every check either passes on it or says why it abstains.

# the measured checks need a capture first; .audit/ is not committed
node <pica>/roles/ux-engineer/scripts/capture-html-reference.mjs --dir html --out .audit
node <pica>/core/scripts/pica-verify.mjs .pica/state.json --evidence
# 33 check(s): 30 passed, 0 failed, 3 abstained.  136 assertion(s) verified.

The three abstentions are named rather than hidden: geometry-diff and frame-inventory-check both want a Figma dump, and build-diff wants a capture of the running demo. Two more are reported separately because they run inside a Figma session and node cannot invoke them at all. Skip the capture and nine checks abstain instead of three, which is the honest number for a project that has not been measured yet.

It is also the mutation suite's fixture, which is what keeps it honest: if a field in it is wrong, the suite stops catching something, and the suite runs on every change.

Who does the work

Seven specialists. Each has a trade of its own, and each reads the sector, the audience and the application archetype before it starts work.

Specialist	Does	Reads about your industry first
discoverer	interviews one group of users and counts what hurts, finds who can stop the project	which people your field always has, and what each of them is afraid of
researcher	measures real products in your field, nine things about each	which products are worth copying here, and which will mislead you
analyst	the real problem, the glossary, the rules, the use cases and the PRD	who can say no, and what your field requires whatever your brief says
modeller	the process across every role, the data model, who may see what, and what states a thing can be in	which shape your kind of application always has, and the screens it always needs
designer	structure first, the direction, the system, then every screen at every state and size	which colours already mean something, how dense, what the field's products look like
writer	the words on every screen, including the ones nobody writes	how your field speaks, and the phrasings it treats as a mistake
reviewer	independent review, and it cannot change anything	what your field already knows counts as a defect

The reviewer cannot change anything. A reviewer who can fix things destroys the record of what was wrong, and quietly makes design decisions that were never theirs to make.

---

Listed so the number can be recounted rather than trusted.

Script		What each one is
trace-check	7	glossary closure, rule enforcement, use case trace, entity terms, AS-IS present, assumption radius, exclusions asked
domain-check	5	all eight categories answered, sourced, verified, agent claims surfaced, affects
industry-check	7	sector known, stakeholders, constraints, conventions, forbidden, style excluded, evidence
archetype-check	4	archetype declared per application, resolved, ambiguity refused, required screens present
audience-check	5	every value resolved, every dimension answered, floors merged by maximum, evidence per selection, ambiguity refused
process-check	5	notation named with a reason, every activity in a lane, every gateway forks, no dead ends, every activity traces to a use case
permissions-check	4	every entity × role cell answered, every entity creatable, every role registered, every permission backed by a use case
requirements-check	4	NFRs as numbers with a condition and a measure, every requirement classified, transition requirements flagged temporary, state model closes
journey-check	4	every lane has a journey, stages derived from the lane, pain carries frequency and class, the delta stated
problem-check	8	metric, baseline, target, guardrail, counter-evidence, generative HMW, tier declared, freeze attributed
discover-check	10	segment defined, sample size, users provenance, evidence class, pain frequency, somebody who said no, stakeholder fears, competitor pricing, bottom-up market, buyer named

parity-check runs wherever two or more viewports are declared, and geometry-diff and frame-inventory-check only where figmaInScope is true.

Every check has been seen to fail on the defect it was written for. The ones that read a Figma port are proven against a faithful dump synthesised from the capture, and the two that run inside Figma by mock-figma.mjs, which implements the part of the plugin API they call. mutation-coverage-check names them on every run and fails if the list grows. You can watch the rest happen:

node scripts/mutate.mjs --fixture            # 180 caught, 0 missed, 0 skipped
node scripts/mutate.mjs <your-project-dir>
node scripts/example-verify.mjs              # the worked example through pica-verify: 0 failed

It reintroduces the defect each check was written for and reports whether that check fires, whether anything else fires with it, and whether your project was clean before it started. It refuses to run over a failing baseline, because a check firing on an already-broken project proves nothing.

It also refuses to count a mutation that changed nothing. Writing the 2.0.0 checks produced two of those: setting a flowchart to flowchart mutates a project that was already a flowchart, and the run reported MISSED rather than letting them pass as caught.

--fixture builds a minimal generic project in a temp directory instead, for when you have no project to hand. It carries less, and says which mutations it had to skip for want of material.

Each check is also recorded next to the failure that earned it in CHANGELOG.md.

Built on the assumption that model judgement is unreliable.

Layer	Fires	Bypassable
SessionStart hook	Always, including after compaction	No
Commands	When you type them, deterministic after that	Yes, by not typing them
PreToolUse hook	On every matching tool call	No

Four things are held by a hook because instructions decay: no Figma write for a package whose design is not approved, none while a review is running, none after delivery, and none before the Figma rules are loaded. Approvals live on disk, because a hook is a script and cannot know you said yes out loud.

---

What ships

Count	What each one is
14 plugins	13 packages plus a bundle, each declaring what it requires, produces, checks and considers done
13 commands	Deterministic once typed
28 rule modules	Loaded per step, never all at once. 228 definition-of-done items across them
26 check scripts	Plus the capture harness, the status tool, and a harness that runs the in-Figma scripts outside Figma
251 checks	Every one fails closed. /pica-verify runs every applicable one in a single table, and an abstention is never counted as a pass
28 sectors	264 names resolving to them, 4 deliberately refused as ambiguous
12 specialists	Each loads its own craft rules and the sector entry before it starts. The evaluator has no write access, because a reviewer that can fix cannot be trusted to report
2 hooks	One loads the rules every session; one refuses a Figma write that has not earned it

Every package brings pica-core with it, so any single install has the state schema and the gates.

Install	You get	Because
pica-business-analyst · pica-ux-researcher · pica-ui-designer	2	they need the state schema and nothing else
pica-ux-engineer	3	it consumes tokens/tokens.css, which research produces
pica-content-designer · pica-evaluator · pica-design-ops	4	all three read the capture artefact html produces
pica	8	the bundle
pica is for	pica is not for
:--	:--
Applications: web, mobile, desktop	Illustration, images, photography
Websites and landing pages	Video, motion, animation
Dashboards, admin tools, internal products	Logos, brand marks, identity work
Design systems and component libraries	Presentation decks and documents
The PRD, use cases and domain model behind them	Diagrams, charts, terminal output
An interactive demo with mock data, and the checks that prove it	The code, the tests and the release pipeline

Tier	Needs	Gives you
Core	bash and python3	Everything: discovery, analysis, design and the checks. All of it except the demo build and Figma
Measured	playwright	The capture harness every measured check reads. Without it nine checks abstain instead of three
Demo	node and a package manager	Building and serving demo.html, the React demo the client uses
Figma	the Figma MCP server, plus a Dev or Full seat	The optional port only, after the freeze
Enhanced	superpowers	Stronger intake and planning, plus the agent panel

The core tier works with nothing else installed. If you never touch Figma, the whole flow runs and ends complete, not truncated.

Loaded per step rather than all at once. 228 definition of done items across them, each either decided by a check or explicitly left to a human.

Module	Package	Covers
intake.md	product-manager	The five-input packet, source authority, the engagement contract, exclusions, the disclosure policy
state-schema.md	core	Every key in .pica/state.json: which role writes it, which checks read it, its shape from the worked example, and the keys nothing validates
research.md	design-researcher	Audit breadth, the direction derived from measurement, token provenance, mock-data provenance, data ownership
design-vocabulary.md	design-researcher	The nine foundations, ten named styles with measurable signatures, style assertions, where to look
direction.md	ui-designer	The sector's settled tradition, spread inside it rather than across it, contrast proved before the palette is offered, reserved hues, what each direction serves badly
craft.md	ui-designer	A floor is not a target: the defects compliance gates cannot see, each named after the screen it came from
structure.md	ux-designer	The lo-fi gate, every screen traced to a use case, greyscale, realistic lengths, every state present, flows with their failures, no dead ends, an IA validated rather than asserted
discovery.md	ux-researcher	Three lists rather than one, evidence classes, frequency over adjectives, somebody who said no, the market derived bottom-up, what competitors charge
business-analysis.md	business-analyst	Elicitation, AS-IS and TO-BE, the delta, business rules, use cases, the domain model, the PRD
domain-knowledge.md	business-analyst	Where domain constraints live in order of authority, Event Storming without a workshop

pica is for	pica is not for
Applications: web, mobile, desktop	Illustration, images, photography
Websites and landing pages	Video, motion, animation
Dashboards, admin tools, internal products	Logos, brand marks, identity work
Design systems and component libraries	Presentation decks and documents
The PRD, use cases and domain model behind them	Diagrams, charts, terminal output
An interactive demo with mock data, and the checks that prove it	The code, the tests and the release pipeline

pica designs things people navigate and someone has to build. If nothing will be implemented from the output, it will get in your way. Nothing in it assumes a client, a stack, a brand or a team.

roles/
  core/        intake, the contract, the state schema, every gate, the hooks, the proposals
  research/    the source audit, the nine foundations, token provenance
  analyst/     elicitation, the sector, audience and archetype data, the models, the PRD
  discover/    users, pain counted, veto holders, the audience profile, the operating model
  html/        the structure gate, the kit, the screens, the React demo, the measured gate
  content/     the words
  designqa/    independent evaluation, and the demo against the approved design
  figma/       the port, the rebuild, the geometry diff, the frame inventory

---

Upgrading

Use install, not update.

/plugin install pica@pica

install brings packages that did not exist in your version. update only refreshes what you already have, and pica then reports the missing checks as SKIPPED. NOT a pass, which is honest and not what you wanted.

Coming from 1.x, uninstall the six that are gone

2.0.0 removed developer, qa, impl, architect, estimate and model. They are gone from the marketplace, which means neither install nor update will take them off a machine that already has them: their commands keep appearing and their rules keep loading, describing a chain that no longer exists.

claude plugin uninstall pica-developer@pica pica-qa@pica pica-impl@pica \
                        pica-architect@pica pica-estimate@pica pica-model@pica

Nothing loads until the session restarts, in either direction.

Philosophy

• Measure, do not eyeball. The defects that matter most survive a visual review
• The cheap medium first. Nothing expensive gets built before the cheap one is approved
• Report before you fix. Finding and fixing are separate passes. An audit that writes is not an audit
• A check must fail closed. If it cannot do its job it exits non-zero, never a clean run over nothing
• A green check is not evidence the check works. Make it fail on purpose before you trust it
• A rule with no register is a preference. If something must be written down it needs a named key in
• A false positive is worse than a miss. A check that cries wolf gets switched off, and then it
• Measurement and review find different defects. Neither substitutes for the other
• Approval is a decision, not an inference. Silence, "looks ready" and moving on are not approval
• Every rule names the failure that earned it. A rule without one gets deleted by the next person
• The last step is a person looking. Measurement narrows what a human has to check. It never
• Issues and questions: https://github.com/vqdungwork/pica/issues
• Changelog: CHANGELOG.md, every rule beside the failure that earned it
• Design notes: docs/specs/ and docs/plans/

---

Issues and questions: https://github.com/vqdungwork/pica/issues   Changelog: CHANGELOG.md, every rule beside the failure that earned it

Contributing. Rules earn their place by naming a failure. A pull request adding one without saying what went wrong will be asked for the failure first. New checks must fail closed, and must be demonstrated failing on the defect they were written for.

Built for Claude Code. Optional integration with superpowers by Jesse Vincent, MIT licensed. MIT, see LICENSE.