PoQ Artifacts
PoQ projects start as intent and become configuration.
The two core artifacts are poq.md and poq.toml:
| Artifact | Role |
|---|---|
poq.md | Plain language human brief |
poq.toml | Executable, deterministic project spec |
People think in poq.md first. The system turns that intent into poq.toml. Operators and developers review the TOML when precision matters.
poq.md
poq.md is where the work is described in normal language.
It should answer:
| Question |
|---|
| What data is being reviewed? |
| What should validators see? |
| What questions should validators answer? |
| What counts as a good outcome? |
| Who should review which items? |
| When should the system ask for more reviews? |
Some features that poq.md can describe in plain language, based on the poq.toml spec, include:
| Feature |
|---|
| Input data mapping |
| Validator classes and requirements |
| Escalation paths |
| Rubric intent |
| Reporting expectations |
See example poq.md documents here, and the poq.toml specification here for all available project configurations.
poq.toml
poq.toml is the structured, specification-compliant version of the project intent.
The app drives the project based on this document. Features defined in the document include ingestion, validation, consensus, routing, and report generation. It declares the concrete features that the engine needs:
| Feature | Configuration |
|---|---|
| Ingestion | Inputs and joins, canonical fields |
| Validators | Validator counts, classes/qualifications, routing, and escalation |
| Validation | Evidence and instructions shown to validators, rubric rows and scales |
| Consensus | Verdict rules |
| Attestation | Settings and format |
Raw rubric answers are ultimately represented as a 0-100 value, even when validators are presented with labels or choices.
How they work together
poq.md is for intent. poq.toml is for execution.
A typical flow:
| Step | Action |
|---|---|
| 1 | Create a concise poq.md. |
| 2 | Upload poq.md during the project creation phase to have the engine generate poq.toml. |
| 3 | Review the engine-generated poq.toml and iterate with the conversational agent. |
| 4 | Finalize the spec and proceed with the remaining phases of the project, such as validation and attestation. |
If the TOML is wrong, the project behaves wrong. The markdown can be informal; the TOML cannot.
What to optimize for
Use poq.md to stay honest about the human workflow. Use poq.toml to make that workflow unambiguous.
For a first project, keep both small:
| Guideline |
|---|
| One clear unit of work |
| A few evidence blocks |
| A short rubric |
| Simple validator assignment |
| Escalation only where uncertainty is expected |
Complexity belongs in the spec only when it reflects a real review need.
Specification reference
This page is conceptual. For the TOML field-level reference, see the poq.toml specification.