Research
Market, users, problem, competition — every claim carrying a source tag.
PIOS
Know what’s worth building.
Describe a product idea in one sentence. PIOS researches it, argues with it, specifies it, and hands you the documents an engineer or a coding agent starts building from.
AI made building cheap. It made building the wrong thing cheap too.
Research that can say no.
not started
gate passed
human checkpoint
The shape of a run
Four moves, in order. None of them optional.
Fourteen gated modules sit underneath these four. A module may not start until every module it depends on has passed its gate.
Validate
Six problem claims kept apart. Insufficient evidence never reported as failure.
Plan
PRD, data model, API contract, architecture, roadmap, build handoff.
Decide
Build, adjust, or do not build — and the last one is a complete result.
What it actually is
Not a program. A body of method.
623 markdown files and 18 YAML files that an AI coding agent reads and executes. You supply the agent; PIOS supplies the discipline. No runtime, no API key, no build step.
Every claim on this page carries the same evidence tag a run would put on its own findings — including the ones further down that say assumption
- Input
- one idea, loosely described
- Gated research modules
- 14
- Dependency edges enforced
- 30
- Documents produced
- 15–17
- Human checkpoints
- 3
- Structural checks, all passing
- 40
- Time
- hours, across sessions
- Licence
- MIT
What you get
One folder, beside the code it describes.
Fifteen required documents, seventeen at most, grouped by when they are read rather than by the module that produced them. A run that concludes do not build still produces every one of them.
00-decision
- 00 Executive-Summary
01-research
- 01 Research-Dossier
- 02 Problem-Validation
- 10 Risks-and-Assumptions
02-product
- 03 PRD
- 04 Feature-Spec
- 08 UX-Flows
- 15 AI-Strategy
03-technical
- 05 Data-Model
- 06 API-Contract
- 07 Architecture
04-delivery
- 09 Roadmap
- 11 Success-Metrics
- 12 Build-Handoff
- 13 Growth-Plan
- 14 Operations-Plan
- 16 Engineering-Setup
Faded entries are produced only when the scope calls for them. Filenames keep their global numbering wherever they sit, so 03-PRD.md means the same document in every cross-reference.
./pios/<slug>/ DECISION.md one page — read this first CLAUDE.md what an AI agent reads to start building state.yaml the audit trail — evidence, assumptions, decisions deliverables/ the five folders above phases/ the board: what may be started now proposal/ proposal.html — send this to get a yes presentation/ engineering-kickoff.pptx
Two of them are what a builder actually works from.
12-Build-Handoff.md states what to build, in what order, and what
“correct” means — readable with no access to the research conversation.
16-Engineering-Setup.md covers environment, seed data, test strategy, CI,
deployment and rollback. PIOS never writes application code.
Readiness
A complete specification is not permission to build.
These get confused every time, because they arrive together: the package is finished, it looks finished, and finished reads as authorized.
A run can and often should deliver engineering_ready: true alongside
commercially_validated: false. That is a complete, honest result —
not an unfinished one.
research_readythe run’s
product_definition_readythe run’s
engineering_readythe run’s
not the run’s to set
commercially_validateda validation result
development_authorizedyours, on the record
A count of ticked engineering boxes says the product is specified. It says nothing about whether anyone will pay for it.
The rules it will not bend
What makes it different is what it refuses to do.
Every claim carries exactly one tag
An untagged claim is a defect. An assumption is never smoothed into a fact — a blueprint that states what it assumed is useful; one that silently asserts it is a liability.
Six claims about a problem are never collapsed into one
Evidence for one is not evidence for another. A problem can be real, recurring and expensively documented, and people will still not pay to prevent it.
01Existence
02Frequency
03Severity
04Business impact
05Solution demand
06Willingness to pay
“Insufficient evidence” is never reported as “failed validation”
The error always runs in that direction, and it converts we did not ask into they said no. Six failure classes keep them apart.
A late answer forces a re-derivation, not a find-and-replace
If an early premise changes after that module passed, every conclusion since is retested to a verdict — survived, changed, or withdrawn.
Your runs are private
They never leave your machine. A gitignore rule, a structural check and a CI step all enforce it. The framework is open; what people put through it is theirs.
Before you install
PIOS asks you questions it refuses to answer for you.
That makes the fit narrower than most tools, and it is worth checking now rather than at the first checkpoint.
It fits if
- You can say who pays and in which country
- You will still be working on this in six months
- You want a verdict that is allowed to say no
- You have a capable coding agent
Skip it if
- You need a PRD in ten minutes
- You cannot yet name the buyer or the jurisdiction
- You have already decided to build regardless
- You want the agent to make the commercial call
Status — v0.2.1
Complete and validated. Not yet proven by use.
Every claim about structure here is verified. No claim about outcomes has been tested by a published run — and a framework that will not smooth an assumption into a fact does not get to make an exception for its own landing page.
Framework — 14 modules, 4 layers eachverified
40 structural checks, all passing in CIverified
Plugin install works outside the repositoryverified
Runs stay private — enforced three waysverified
Portable to any file-writing agentinferred
Reference runs publishednone yet
Produces better product decisionsassumption
Install
Two commands, then one sentence.
Claude Code is the reference implementation. Any agent that reads and writes files can run
it from AGENTS.md instead.
# install once $ claude plugin marketplace add iamibrahimriaz/pios $ claude plugin install pios@pios # then, from any project directory $ /pios:research an app that helps small gyms manage memberships # resume later — a full run does not fit in one session $ /pios:research $ /pios:research what stage am I at?