Define your spec
PoQ projects start as intent and become configuration. Every project runs on one artifact: poq.toml, the executable, deterministic spec the engine reads. Everything else on this page is a way of arriving at it.
Three ways to get a spec
You can arrive at poq.toml from any of three starting points. When you upload a folder during project creation, PoQ scans it for spec artifacts and picks the path for you, in order of precedence:
| What you bring | What PoQ does |
|---|---|
A finished poq.toml | Validates it and uses it directly. No model is involved. |
A plain-language poq.md brief | Compiles it into a poq.toml draft for you to review. |
| Nothing but your data and your intent | Opens the conversational agent, which interviews you and drafts the spec with you. |
All three end at the same place: a valid poq.toml that you review before the project runs.
poq.toml wins over poq.md when both are present. If the poq.toml is invalid and a poq.md is present, PoQ compiles the brief instead of blocking you. If it is invalid and there is no brief to fall back on, you get the validation errors and nothing is created.
Key information for spec derivation
Whichever path you take, the spec has to settle the same decisions. Knowing them in advance makes every path faster: the agent will raise them as questions, your poq.md should describe them in plain language, and your poq.toml must declare them as parameters.
| Decision | What it settles | Required? |
|---|---|---|
| Validation goal | What a validator decides about one item | Yes |
| Ingestion | Which files become datapoints, how they join, which fields are canonical | Yes |
| Evidence | What each validator sees, such as markdown, code, images, source links, and facts | Yes |
| Rubric | The dimensions scored, each with a scale and answer labels | Yes |
| Validator count | How many validators review each datapoint by default | Yes |
| Reward | What each validation slot pays, in USD | Yes |
| Stake | Collateral each validator posts per slot | Only for staked assurance |
| Validator classes | Named tiers or specialists, human or AI, with their own rewards and rules | Only when the work needs them |
| Qualifications | Credentials a validator must hold to claim an item | Only when the work needs them |
| Routing | Which items go to which class of validator | Only when the work needs them |
| Escalation | What happens when a panel disagrees, such as adding reviewers or a senior tier | Only when the work needs them |
| Consensus weighting | Whether some validators' answers count for more than others | Defaults to equal weight |
| Attestation | How verdicts are sealed and reported | On by default |
Without the required rows, a spec will not validate. The optional rows are where most projects get complicated, so add them only when the work calls for it.
Conversational agent
The conversational agent defines a spec with you inside the app, without you writing either artifact by hand. It is the path when you have data and intent but nothing written down.
It works in two stages:
| Stage | What the agent does |
|---|---|
| Decide | Reads your uploaded data, proposes the validation goal, evidence, and rubric in plain language, and asks you to confirm what it cannot infer |
| Author | Turns the confirmed decisions into poq.toml, then keeps editing that spec as you ask for changes |
Once the agent has produced a spec, you can ask for changes in plain language, such as "make the rubric stricter" or "add a second reviewer". It revises the existing TOML rather than starting over. That same conversational editing is available after the spec is generated, whichever path produced it.
The agent does not ask about everything. Ingestion is settled earlier, when you finalize your data. Validator qualifications and compensation are configured in a later project-creation step rather than in the conversation.
poq.md
poq.md is where the work is described in plain language. Use it when you are bringing a brief you already wrote, or when you would rather author intent outside the app and version it alongside your data.
A brief should answer the key information above, as far as your project needs it: every required decision, plus the optional ones the work calls for.
Compiling a brief into a spec is a single model pass, so read the draft it produces before you run the project. See example poq.md documents here.
poq.toml
poq.toml is the structured, specification-compliant version of the project intent. Hand-author it when you want precision, repeatability, or a spec under version control.
The app drives the project based on this document. Features defined in the document include ingestion, validation, consensus, routing, and report generation. The poq.toml specification is the source of truth for every section, field, type, and default.
Raw rubric answers are ultimately represented as a 0-100 value, even when validators are presented with labels or choices.
See example documents here.
See also
| Page | Description |
|---|---|
poq.toml Specification | The source of truth for every field, type, and default |
poq.md examples | Worked briefs for common project shapes |
poq.toml examples | Worked specs for common project shapes |
| Supported data types | What files ingestion understands and how datapoints are formed |