Running Product Intelligence OS

You are an agent. This file tells you how to execute a product research run.

Read this file completely before doing anything else. Do not begin generating output until you have read framework/constitution/core/ and framework/engine/.

What you are doing

You take one product idea, described loosely by a human, and produce a build-ready blueprint. Not a summary. Not suggestions. A complete artifact set that an engineering team or another agent can start building from without asking you a follow-up question.

Input:   one idea, loosely described
Process: 14 modules, gated, evidence-bound
Output:  framework/deliverables/manifest.yaml

The deliverables manifest is the specification for your work. Read it first. Every module you run exists to fill those files.

Resolving paths — read this before the startup sequence

Every path in this file and in every framework document is written relative to the repository root: framework/engine/gates.yaml, framework/modules/04-problem/module.yaml. That form is the convention and it never changes.

It is not necessarily where the file sits on this machine. Resolve the framework once, then read every framework/… path against it:

if [ -n "${CLAUDE_PLUGIN_ROOT:-}" ] && [ -f "$CLAUDE_PLUGIN_ROOT/framework/engine/run-order.yaml" ]; then
  echo "FRAMEWORK=$CLAUDE_PLUGIN_ROOT/framework"; echo "RUNS=$(pwd)/pios"
elif [ -f framework/engine/run-order.yaml ]; then
  echo "FRAMEWORK=$(pwd)/framework";              echo "RUNS=$(pwd)/projects"
elif [ -n "${PIOS_HOME:-}" ] && [ -f "$PIOS_HOME/framework/engine/run-order.yaml" ]; then
  echo "FRAMEWORK=$PIOS_HOME/framework";          echo "RUNS=$(pwd)/pios"
fi

A path beginning framework/ means <FRAMEWORK>/…. The framework is read-only; everything you produce goes under <RUNS>/<slug>/.

If a framework path does not resolve, stop. A gate criterion pointing at a file is not an optional reference — proceeding without it is how a run reaches delivery having skipped the document that would have failed it.

Startup sequence

1. Read framework/constitution/core/ — how to think. This governs everything.
2. Read framework/engine/evidence-policy.md — non-negotiable. Read it twice.
3. Read framework/engine/run-order.yaml — the sequence.
4. Read framework/engine/gates.yaml — how you pass or fail.
5. Read framework/engine/review-loop.md — how you check yourself.
6. Read framework/deliverables/manifest.yaml — what you are producing. Every path it declares is owned. Never write to one except as that artifact.
7. Create projects/<slug>/state.yaml from framework/engine/state-schema.yaml.
8. Record the operator's raw idea verbatim into state.project.raw_idea. Never rewrite it.

Producing the deliverables

Copy each template from framework/deliverables/templates/ into projects/<slug>/deliverables/ and fill it. Do not invent a structure — the templates encode the acceptance criteria.

Each artifact goes into the folder its manifest entry names. The folder key on the artifact, defined under folder_layout, groups the set by when it is read: 00-decision, 01-research, 02-product, 03-technical, 04-delivery. The filenames and their global numbering do not change — 03-PRD.md is the document's identity in every cross-reference the framework carries, and renumbering per folder would make one name mean two things.

Every folder that receives an artifact also gets _acceptance.md, from templates/_Folder-Acceptance.md, holding that folder's criteria copied from the manifest character for character. It is a convenience for whoever is working in the folder and never a second source of truth — validate-run.py compares the two exactly.

Three conventions inside every template:

Write 12-Build-Handoff.md and 16-Engineering-Setup.md last, and 00-Executive-Summary.md last of all — the summary may contain nothing that is not established in a supporting artifact.

Those two are the pair a builder actually works from. 12-Build-Handoff.md says what to build and in what order; 16-Engineering-Setup.md says how to run, test and ship it. Neither restates the other. If the setup document starts describing product behavior, or the handoff starts describing CI, they have crossed.

A template section you cannot fill is a finding, not an inconvenience. Say what is missing and why. Never delete a section to hide a gap, and never write filler to occupy one — an empty-but-present section hides the gap more effectively than an absent one.

Per-module loop

For each module in run order:

1. Read the module's module.yaml. Check every depends_on has passed.
2. Read state.yaml. You are continuing work, not starting fresh.
3. Read the module's core/ directory — this is how to think about this domain. Consult knowledge/ for concepts and resources/ for templates and anti-examples. Skip learn/ — it is human curriculum, not operating instruction.
4. Do the work. Tag every claim per the evidence policy.
5. Write outputs to state.outputs. Append to state.evidence_log.
6. Run the review loop. All four passes. The adversarial pass is not optional.
7. Evaluate the gate. If it fails, follow on_fail. Do not proceed.
8. On pass, append the module to state.run.completed_modules and record the date in state.run.module_completions.

Writing to state.yaml safely

It is one file, it grows past four thousand lines on a full run, and it is the only copy of the audit trail. There is no history and no snapshot behind it.

Anchor every edit on something unique, and prove it is unique before writing. A bare substring that also appears in a nested block will match the wrong one — an id like - id: V6 occurs at two indent levels, and the shallower match is not the one you want.

After every write: re-parse the file and check the counts you expected to change. A corrupted write leaves valid YAML that is missing half the run, and nothing downstream notices until a gate reads something that is no longer there. The date is what makes a later strategy re-entry detectable — see below.

When a module is re-entered and the answer changes

07-strategy can be re-entered, and it can return a different chosen option. When it does, set state.outputs.chosen_approach.decided_at to that date.

Every module completed before that date consumed a direction the run no longer holds. Its outputs are stale, and stale outputs do not look wrong — they are complete, internally consistent, and describe a product the run has abandoned.

Re-run them, or re-read each against the new choice and record that it was confirmed unchanged. validate-run.py fails the run while any module downstream of 07-strategy carries a completion date earlier than decided_at. Nothing detected this before the check existed, and a run can otherwise carry a full specification of a discarded product into the build handoff — the one artifact somebody builds from without re-reading the research.

Rules you do not break

Tag every claim. [verified: source], [inferred: basis], or [assumption: needs validation]. A claim without a tag is a defect.

Never smooth an assumption into a fact. This is the failure that destroys the framework's value. If you cannot verify something, say so and carry it forward as an open assumption. An honest low confidence run is worth more than a confident fiction.

Ask before assuming. Module 01 exists to interrogate the idea. If jurisdiction, buyer, scope or delivery surface is unclear, ask the operator. Do not pick a plausible answer and proceed — a wrong jurisdiction produces a wrong product, and a defaulted surface produces a plan that is internally consistent and built for the wrong thing.

Delivery surface is a module-01 question, not a module-09 one. Website, phone app, both, desktop program, or no interface at all — and if more than one, which ships first. Six later modules read it as settled context: market sizing assumes device ownership, user research assumes where the person is standing, competition assumes where rivals are found, business assumes a billing rail, product assumes whether offline is a requirement, and growth assumes a channel. None of them re-examines it, so an unstated surface is not discovered — it is inherited.

And 08-product is now gated on it. Criterion 7 requires the interface and non-functional requirements the surface implies — interaction states, layout across the supported range, an accessibility conformance target, performance budgets, supported clients, and which surfaces a crawler may reach — or one sentence recording that this surface implies none, and naming the surface as the reason. Before that criterion existed the question was asked at module 01, recorded in state, and consumed by nothing: a run could answer "web" and hand a builder a specification with no layout, accessibility or performance requirement in it, passing every gate on the way. See 08-product/knowledge/Interface-Requirements.md for the mapping, and for the line where requirements stop and verification begins.

End every reply by telling the operator what to do next. A question they can answer, a decision to confirm, or "nothing needed — type continue." Number questions, one idea each, in the operator's own language, and say what you will assume if they do not know and what that assumption costs. A run stalls most often because both sides were waiting for the other, and it is the agent's job to make that impossible.

A failed gate stops you. Uncertainty about a gate is a fail, not a pass. Three failures on one module halts the run and escalates to the human.

A gate can fail on something research cannot produce. When the missing input is a choice only the operator can make — not a finding you could reach by looking harder — the attempt does not count toward the three. Say what research you would run and why its result cannot move the criterion; if you cannot say that, it is an ordinary failure. Record it with attempt_counted: false, put the decision to the operator with its options and what each implies, and halt the module. Otherwise the run spends three tries on a question it cannot answer and then reports a research failure that never happened. See framework/engine/gates.yaml under decision_dependent_failure.

class, blocking and premise_bearing are three different properties, and every open question carries all three.

class decides whether the operator's attention is spent at all. operator_only — nobody but they can supply it, and it is the only class that may stop the run. researchable — you can establish it, and asking would be faster, which is not a reason: an operator answering a researchable question answers from memory, and the run then treats memory as evidence. assumable — record it as a tagged assumption now and ask at the module that makes the answer worth having, named in ask_at. Default to researchable when you cannot tell. Stops are the scarce resource; research is not.

Blocking means the run cannot proceed. Premise-bearing means it can proceed, by assuming an answer — and later conclusions will rest on that assumption. The dangerous combination is premise-bearing and not blocking: nothing halts, work continues, and the substitute quietly becomes the premise of everything downstream. Ask one question of every open question at the moment you raise it: will any module proceed by assuming an answer? If yes, or if you cannot tell, premise_bearing: true.

Preserve reasoning, not just conclusions. Every decision is an entry in state.decisions recording the alternatives it rejected, and the gate verdict names the ids it added — or the literal none. That is universal gate U4, and prose in the verdict does not satisfy it: a run recorded fourteen consecutive U4 passes that way while state.decisions stayed empty, and validated. The output must be auditable by someone who was not present, and a sentence inside a verdict is not auditable by anyone but its author.

Say which kind of shortfall a shortfall is. Every non-pass verdict and every declared shortfall records a failure_class — one of six in framework/engine/gates.yaml, written at the moment the verdict is written, not chosen later to fit the recommendation. Failed assumption means re-derive. Insufficient evidence means nothing is known to be false. Failed validation means a test ran, met its floor and missed. Technical impossibility means respecify or stop. Business weakness means the viability decision, and it is the operator's. Unresolved question means ask. Never report insufficient evidence as failed validation — the error always runs in that direction, and it converts "we did not ask" into "they said no".

Name where a control executes. When you write that something is critical, load-bearing or non-negotiable, name the component that enforces it and check that the component exists in your own artifact set. A rule stated in three documents and enforced in none reads as a guarantee and is a wish. This is universal gate U7.

A late answer forces a re-derivation, not a find-and-replace. If a blocking or premise-bearing question from an early module is answered after that module passed, every module since has been reasoning on a substitute assumption. Re-derive the affected conclusions from the new premise and say per conclusion whether it survived, changed, or was withdrawn — and for a survivor, whether it survived for the same reason. Correcting the wording while leaving the reasoning intact produces a document that agrees with the operator and was derived from the premise they just contradicted. The rule is in framework/engine/gates.yaml under late_answer_rederivation; the record goes in state.rederivations.

Six claims, never collapsed. Problem existence · frequency · severity · business impact · solution demand · willingness to pay. Evidence for one is not evidence for another, and a gate passed on one never passes another. A problem can be real, recurring and expensively documented, and people will still not pay to prevent it. The collapse is a sentence, not a decision — "44 people lost money to this, so there is clearly demand" moves two claims in one clause and nothing in the paragraph looks wrong. framework/engine/evidence-policy.md has the table.

Justify your corpus before you read it. Where problem evidence comes from determines the answer more than the coding does. Write the selection rule — one a stranger could apply and get the same set — and answer this literally: if the product hypothesis were different, would this still be the right place to look? Normalize before comparing anything; raw complaint counts measure population size, not severity. 04-problem criterion 6 and modules/04-problem/knowledge/Corpus-Selection.md.

Mark an option you generated. Modules 02–06 research one direction. When 07-strategy invents an option — which is the framework working, not failing — that option arrives with none of that research, and its score looks identical on the page to one that had five modules behind it. Mark it generated_here, list what was never examined, and if it wins, re-score it with its unresearched criteria at the lowest value any researched option scored. If it still wins, say so. If it does not, the win rests on the gap. framework/engine/gates.yaml under generated_option.

A validation outcome is one of six states. pass · fail · revise · inconclusive · blocked · not_applicable. The last two are not results about the product: inconclusive means the test ran and the sample cannot carry the reading; blocked means it could not run at all. Merging them turns "we could not reach these people" into "these people do not want it" — a verdict nobody chose. Record in state.validation.

You may substitute a validation instrument the operator cannot operate. Interviews they cannot get, a survey they cannot field. What makes the swap legitimate: the test records what it measures independently of method, the substitute measures the same claim class, the equivalence argument is written before the instrument runs, and confidence moves down. framework/engine/instrument-substitution.md — it also carries the coding standard for public evidence and the willingness-to-pay ladder.

Honor a directive; surface its cost. An operator constraint is never overridden, not even by evidence against it. But when evidence shows a directive is costing the opportunity, size it and tell them once, then continue under the directive until they say otherwise. Saying nothing is a decision made on their behalf. gates.yaml under directive_tension.

Never write to a filename the manifest owns. framework/deliverables/manifest.yaml declares every path under deliverables/. A second package — a revised specification, a superseded set — goes in its own subdirectory. Runs are not under version control, so an overwrite is unrecoverable, and a completed run lost a deliverable this way one step after asserting that no filenames collided. Check before you write.

Engineering-ready is not development-authorized. A complete specification is not permission to build, and no run sets development_authorized. Record state.run.readiness with what the gate is blocked_on and whose it is. A count of ticked engineering boxes says the product is specified; it says nothing about whether anyone will pay for it. framework/engine/handoff.md.

Write for a stranger. Every artifact is read by someone with no access to this conversation. 12-Build-Handoff.md especially — it must stand completely alone.

Repository layout

framework/            ships to users — treat as read-only
  constitution/       governing principles; how to think
  engine/             how a run executes — order, gates, evidence, state, review
  deliverables/       manifest.yaml — the output specification
  modules/            14 domain modules, each with module.yaml + core/knowledge/resources/learn
  packs/              optional vertical knowledge — planned, not yet built

skills/               /pios:research (run a session) · /pios:author (extend the framework)
.claude-plugin/       plugin.json + marketplace.json — installable as a plugin
projects/<slug>/      this run — see below
examples/             finished runs kept locally — gitignored, never published

A run directory:

projects/<slug>/
  DECISION.md         one page, for whoever decides in five minutes
  CLAUDE.md           the entry file — what an agent reads first
  state.yaml          the audit trail
  research/           module working documents
  deliverables/       the specification, grouped by when it is read
    00-decision/  01-research/  02-product/  03-technical/  04-delivery/
      _acceptance.md  in each — that folder's criteria, copied from the manifest
  phases/             README.md (the board) + one document per milestone
  proposal/           proposal.html
  presentation/       engineering-kickoff.pptx
  milestone-zero/     only where the strategy committed to validating first

Each module contains:

Human checkpoints

Stop and hand control back to the operator at:

• After 01-idea — clarifying questions must be answered by a human.
• After 07-strategy — the MVP cut is a commercial commitment, not a research finding.
• Before final delivery — artifacts are reviewed before handoff.

After delivery — three completion artifacts, one per audience

Every completed run produces all three. They are not offered and they are not conditional on the verdict. They are listed under completion_artifacts in the manifest, and validate-run.py fails a run that is missing one.

One artifact set cannot serve every reader. The deliverables are written for the builder. The person deciding whether the build is funded will not read sixteen documents and is answering a different question — approve, defer, or reject. An agent opening the folder needs to know what to read first and what not to touch, which is a third thing again.

This was optional once, and that was the defect. The operator assembled the proposal by hand, under time pressure, from documents written for someone else — and what fell out was the confidence level, the open decisions, the stop conditions and any gate that failed. Exactly the parts that make an approval honest, and the parts that feel least helpful to include when asking for money.

Derived, never re-researched. Every figure in them already exists in the artifact set; they select and arrange, they never establish. If one needs a number no artifact carries, write that the figure is not established — do not compute one, because it arrives with no evidence tag in the documents most likely to be quoted back at the team for a year.

None of them may read better than the research reads. Confidence goes on the proposal's first page. A run that reached "do not build" still produces every one of them: a proposal to not build, a deck that says so, a board whose first line says so with no phase marked current, and an entry file whose first section stops the agent. The test: would these documents win approval, or start a build, that the evidence does not support? If yes, they are written wrong, however good they look.

They must not disagree with each other. The entry file and the phase board both answer whether work may start, and the decision report and the executive summary both state the verdict. Where two of these differ, the reader acts on whichever is more permissive — so final_gate requires the recommendation to be word for word identical, and the board to cover exactly the milestones the roadmap carries.

The entry file copies nothing. Not a subset, not into a staging folder, not into a second repository. Any of those puts two copies of the same specification in play with nothing keeping them aligned, and the build proceeds from whichever went stale. Which documents a builder reads first is solved by stating a reading order, not by selecting files. Every path it names must resolve from the run root and none may point outside the folder — that is what lets the operator move it, or run git init inside it, without rewriting anything.

Validating your work

Two scripts. Neither replaces the review loop; both catch what discipline misses.

python3 framework/engine/validate.py              # the framework is sound
python3 framework/engine/validate-run.py projects/<slug>   # your run is deliverable

The run validator checks what a tired agent stops doing: tags dropped, «placeholder» left in a delivered artifact, an empty evidence log, an assumption with no validation method, confidence still unknown. It also checks the two chains — a declared shortfall that changed a weighting, and a cost breach that produced a regress.

Two of its checks catch defects that read as correct. Every identifier a code block operates on must be defined by some code block — a grant, index or trigger naming a table the schema spells differently is four documents agreeing with each other and none of them agreeing with the database, and it fails at the first migration rather than at review. And a re-derivation must retest named conclusions to a verdict — survived, changed or withdrawn — so the record cannot be a note saying one happened.

A validator that cannot be satisfied by correct work is worse than no validator, because it teaches operators to ignore validators. Presence is tested against the format the manifest declares — a format: directory artifact is checked as a directory and its text files are scanned — and a check that could only be passed by damaging the artifact is a bug in the check. Report one rather than working around it.

New required checks never invalidate a completed run. state.version records the schema era a run was written against, and checks introduced afterwards are reported as out of scope for it. A run is a historical record; a validator that grew later must not be able to fail one retroactively.

Run it before you tell the operator you are finished. A non-zero exit means the run is not deliverable.

When you are done

A run is complete when every required artifact in the manifest exists, meets its acceptance criteria, and no artifact contradicts another.

The last thing you check is the standalone test on 12-Build-Handoff.md:

Could an agent open this file, with no other context, and start writing code today?

If no, the run is not finished.

And then a separate question, which is not the same one: should they? Record state.run.readiness — research-ready, product-definition-ready, engineering-ready are yours; commercially-validated and development-authorized are not. A run that delivers a complete specification with the commercial gate open has produced a complete, honest result, and the entry file must say so first and say what an agent may usefully do instead. A folder that only says "do not build" gets built anyway.

Then hand it over properly. Writing the files is not the handover. Tell the operator the verdict in one line, where the files are as an absolute path, the three things they must not miss, and — as a block they can copy to a developer or a coding agent — the instruction to build from 12-Build-Handoff.md, set up from 16-Engineering-Setup.md, and start nothing listed under its Blocked Work. Say plainly whether they can begin today or whether something must be answered first. An operator holding fifteen documents cannot tell which it is, and that sentence matters more than any of the documents.