This document summarizes how the workflow stages connect. Each stage outputs one compact package. Downstream stages should read the approved package rather than reconstructing context from scattered notes.
Before the workflow enters Planning, the researcher agent should run a short setup gate. This setup gate is not a research stage and does not produce a Planning package. It determines how the rest of the workflow should be led.
The setup gate has two decisions:
- Confirm the active role configuration from
WORKFLOW-CONFIG.md. - Ask the user to choose the workflow mode and reviewer strategy.
Workflow mode choices:
| Mode | Meaning | Default use |
|---|---|---|
| Auto-until-needed | The researcher agent proceeds through the workflow and stops only at gates, missing information, route-changing decisions, or genuine uncertainty/problems. | smoke tests, mature ideas, speed-first internal work |
| Step-by-step discussion | The researcher agent discusses each meaningful step or decision with the user before expanding the package or moving on. | broad, uncertain, high-stakes, or collaborative projects |
Reviewer strategy choices:
| Option | Meaning |
|---|---|
| Use reviewer | Run the maker-checker loop before the user gate: review request, reviewer critique, researcher response, then gate. |
| Skip reviewer | Record the skipped-review reason, accepted risk, and revisit trigger in the package before the user gate. |
Recommended default for real research: Step-by-step discussion plus Use reviewer. Recommended default for smoke tests: Auto-until-needed plus synthetic gates and either skipped reviewer with recorded risk or a clearly labeled synthetic reviewer pass.
After the setup gate, the researcher begins Planning orientation using the selected mode.
For real research projects, Planning orientation is followed by at least a focused prior-work and novelty calibration before the Planning Package is treated as gate-ready. The calibration may be light, but it should check whether the idea has already been studied, what adjacent work did, and what research value remains. It may be skipped or deferred only when the user explicitly chooses that route or the project is clearly a smoke test/demo, and the package must record the skipped/deferred reason, accepted risk, and revisit trigger.
| Stage | Primary input | Primary output | Gate |
|---|---|---|---|
| Planning | user need, focused prior-work/novelty calibration or explicit skip/defer rationale, idea maturity, feasibility checks, research-skill cards or skill candidates, Planning Reviewer critique, researcher-agent response/fix | Approved Planning Package | Planning Gate after reviewer response |
| Modeling / Execution | Approved Planning Package | Modeling Package, often after an exploratory demo phase inside Modeling | Modeling Gate |
| Reporting / Output Packaging | Approved Planning Package + Modeling Package | Reporting Package and reader-facing deliverables | Reporting Gate |
| Reviewing | Approved Planning Package + Modeling Package + Reporting Package | Review Package | Reviewing Gate |
The default route is:
- Planning
- Modeling / Execution, usually starting with a small exploratory demo when the workflow is new or uncertain
- Reporting / Output Packaging
- Reviewing
Reporting produces the reader-facing outputs. A paper, report, slide deck, dashboard, web page, software package, technical appendix, or review packet is a Reporting output mode, not a separate stage. Reviewing happens after Reporting because reviewer agents need a concrete package and deliverables to inspect.
The researcher agent is responsible for driving the workflow. The user should not need to remind the agent what the next stage action is.
At the start of every stage, the researcher agent should state:
- current stage
- package path being created or revised
- immediate next action
- expected stop condition
- user decision needed now, if any
At the start of Planning, the researcher agent should use a confirmation-led orientation:
- "I understand you want to do X."
- "I propose to run this workflow as Y."
- "The active stage is Planning, and I will create or revise Z package."
- "If that is right, I will proceed; if not, correct the part that is wrong."
This orientation is not a questionnaire. The researcher may ask a concise question only when the answer would change the route, such as the research question, final output, gate mode, domain/source choice, implementation location, or claim level. Once the intent is clear enough to plan, the researcher should start the Planning package rather than keep asking for preferences.
The researcher agent should proceed within the current stage until a real stop condition is reached: missing information, missing files or permissions, reviewer handoff, user gate, or an explicit user pause. When it stops, it should name the next concrete action or decision rather than ending with an open-ended request.
For real projects, Planning begins with orientation and proposed user-need confirmation, not with filling every package. Modeling, Reporting, and Reviewing remain inactive until the upstream gate approves them. Existing downstream templates in a scaffold are placeholders only and should stay marked as not started.
User confirmation of the topic or rough research direction is not Planning Gate approval. Do not start Modeling after the user merely agrees that the proposed research idea is interesting or worth exploring. First complete or explicitly defer the prior-work/novelty calibration, write the Planning Package, run or record the reviewer pass, and ask for the Planning Gate decision.
User-need confirmation does not mean waiting for the user to design the workflow. The researcher owns the next proposed action. It should make a reasonable proposal, present likely answers for decision-shaping fields, surface assumptions that would materially affect the project, and then move once the user confirms or corrects the proposal.
Each stage uses the same internal pattern before its user gate:
Researcher agent produces or revises the stage package
-> Reviewer agent critiques the package and deliverables
-> Researcher agent responds, fixes, defers, rejects with reason, or escalates
-> User gate
Reviewer agents critique only by default. They should not modify files unless the user explicitly authorizes edits. Reviewer findings should be recorded in the stage package or linked as an agent artifact. The researcher-agent response must classify each finding as accepted and fixed, accepted but deferred, rejected with reason, or needing user decision.
If a reviewer-agent pass is skipped for any stage, the stage package must record the reason, accepted risk, and revisit trigger before the user gate is presented as ready.
Backtracking is normal. It is not a system failure.
| Trigger | Typical route |
|---|---|
| research question, idea maturity, or scope is wrong | Reviewing/Reporting/Modeling -> Planning |
| prior-work or novelty basis is too weak for the target claim | Reviewing/Reporting -> Planning or targeted literature addendum |
| data cannot support the approved method | Modeling/Reviewing -> Planning |
| exploratory demo does not pass basic feasibility or value checks | Modeling -> Planning or revise Modeling demo |
| code, robustness, extraction, validation, or empirical figure is missing | Reporting/Reviewing -> Modeling |
| evidence package is hard to inspect or lacks provenance | Reviewing -> Reporting |
| target venue or output route does not fit | Reviewing/Reporting -> Planning or Reporting |
| citation, source-support, or deliverable gap is local | Reviewing -> Reporting or targeted literature addendum |
| manuscript, slide, web, dashboard, or software-package argument is weak or report-like | Reviewing -> Reporting |
| project is infeasible, noncompliant, or misleading | Any stage -> Terminate |
The workflow should avoid creating many unreviewed side artifacts. Extra files can exist for code, data, figures, validation outputs, working notes, and drafts, but each stage should summarize them in its package.
For real research projects, create a dedicated project folder under
research/<research-name>/ and use the layout in
research-organization.md. New project packages
belong in research/<research-name>/packages/; detailed notes belong in
research/<research-name>/notes/; run-scoped review requests, critiques,
manifests, and logs belong in research/<research-name>/artifacts/<run_id>/.
For discussion-first projects, do not force all work into the stage package at once. Use supporting notes or matrices for detailed exploration, and keep the stage package as the compact checkpoint that records accepted decisions, open questions, evidence status, and links to details. The researcher should consolidate only after the relevant sub-step has been discussed or accepted by the user.
Only the active stage package should be substantively edited. Downstream package templates may be created for scaffolding only when useful, but they must not be filled, interpreted as progress, or presented as active stage outputs before the workflow reaches those stages.
Required packages:
templates/plan-package.mdtemplates/model-package.mdtemplates/reporting-package.mdtemplates/review-package.md
Supporting templates:
templates/research-skill-card.mdtemplates/smoke-test-package.md
Worked examples should not keep every file in the example root. Use the layout in example-organization.md:
packages/for approved Planning, Modeling, Reporting, and Reviewing handoffsdeliverables/for final or near-final reader-facing outputsnotes/for literature, feasibility, method, and other working notesartifacts/for input, data, code, logs, tables, figures, validation outputs, and run-specific agent artifactsarchive/for superseded files kept only for traceability
The example root should usually contain only README.md, run-notes.md, and the main folders above. This keeps the approved package flow separate from generated evidence and exploratory notes.
For substantial runs, especially exploratory demos that may later scale up, maintain:
artifacts/<run_id>/run_manifest.jsonfor version, scope, inputs, outputs, tools, and statusartifacts/<run_id>/run_log.mdfor chronological decisions, failures, repairs, and gate notesartifacts/<run_id>/run_summary.mdfor the human-readable summary of what the run proved
If agent-specific skills, prompts, critiques, or coordination notes are created during a run, store them under:
artifacts/<run_id>/agent/
Promote only reusable, evidence-backed agent methods into skills/. Keep run-specific agent material in artifacts.
Each gate should answer three questions:
- Is the stage output scientifically acceptable for its stated claim level?
- What must be changed before downstream use?
- Should the workflow proceed, revise locally, backtrack, scale up, finalize, release, archive, or terminate?
For autonomous framework tests, gate decisions must be labeled as synthetic gates rather than real user approvals. Synthetic gates are acceptable for smoke tests and QA runs, but they do not replace user, domain-owner, or expert approval in a real research project.
When the runtime provides a structured user-choice tool such as
request_user_input, the researcher agent should present each real user gate
with clickable choices instead of relying only on free-text replies. The prompt
should still summarize the package, reviewer findings, researcher response, and
consequences of approval before asking for the choice.
Use 2-3 mutually exclusive gate choices. Put the recommended choice first and label it as recommended only when the evidence supports that recommendation. Always leave room for the user's free-form correction or condition. If the structured-choice tool is unavailable, present the same choices as plain text.
Default gate choices:
| Gate | Structured choices |
|---|---|
| Planning Gate | Approve for Modeling / Revise Planning / Backtrack or terminate |
| Modeling Gate | Approve for Reporting / Revise Modeling / Backtrack to Planning |
| Reporting Gate | Approve for Reviewing / Revise Reporting / Request Modeling or Planning addendum |
| Reviewing Gate | Finalize or archive / Revise routed issues / Backtrack to earlier stage |
Gate approval is an action, not only a status label. When the user approves a stage, the default behavior is to immediately begin the next downstream stage in the same turn if there is enough context and no explicit pause request.
Default transitions:
| User approval | Default next action |
|---|---|
| Planning Gate approved | Start Modeling by locking the modeling contract and, when appropriate, running a small exploratory demo first; this requires recorded Planning Reviewer critique or a recorded skip rationale plus researcher-agent response |
| Modeling Gate approved | Start Reporting / Output Packaging by ingesting the approved Planning and Modeling packages |
| Reporting Gate approved | Start Reviewing by stress-testing the evidence package and writing a Review Package |
| Reviewing Gate approved | Finalize, submit, share, archive, run a routed Modeling/Reporting addendum cycle, backtrack, or terminate according to the selected route |
The workflow should pause after approval only when:
- the user explicitly says to stop, pause, or wait
- the next stage needs information that cannot be inferred safely
- required data, tools, permissions, or files are unavailable
- the approval is conditional and the condition must be resolved first
If a stage is approved but the next stage cannot begin, the package should state why and list the smallest next action.
At each gate, Codex should guide the user with a short decision prompt:
- current stage and package produced
- what was completed
- what decision is needed
- what will happen if the user approves
- what alternative routes are available
- structured clickable choices when available, with a free-form path for conditions or corrections
Use concrete language such as:
This completes the Modeling package. The exploratory demo phase has been incorporated into the Modeling evidence and revision notes. If you approve the Modeling Gate, I will move to Reporting / Output Packaging. Alternative routes are: revise Modeling, narrow the scope, or return to Planning.