# The AI Workflow Method — v1.0

Method version: **1.0.0** · Released as a reviewable specification on November 7, 2026.

An objective becomes a plan; each stage produces evidence; checks determine whether work proceeds, needs correction, or waits for a person. The deliverable includes the result and a record of how it was reached.

**Define → Plan → Execute → Record → Verify → Deliver**

On failure: **Record defect → Correct → Recheck**. On interruption: **Save checkpoint → Verify source state → Resume**.

## What is actually implemented?

The existing Research Engine v2.0 prepares instructions and a project manifest in the browser. It offers new-project and checkpoint-import modes, optional device storage, copy and download. It validates imported fields and downgrades imported completion claims to verification pending. Its build excludes private project catalogs unless opted in, and public artifact exports require approval flags, existing files and matching hashes. It does not run research, authenticate scientific reviewers, synchronize GitHub or maintain a background execution queue.

Its research prompt already requires ten stages, feasibility decisions, source-linked extraction, immutable inputs, defect tracking, human reviews and honest checkpoints. Those are **instructions to an execution agent**, not enforced research services.

This v1.0 package separates that general process from the scientific playbook. `controller.cjs` adds an **optional, local state helper**: ordered gates, on-disk artifact hashes, criterion records, scoped approval records, bounded retries, downstream invalidation after correction, checkpoint revision checks and a hash-linked event record. Tests exercise these controls. The website does not call this helper; it must be used by an execution host or an operator. It has no AI/model, network, scheduler, identity service or external action integration. Approval records rely on a trustworthy operator; they do not prove a human reviewed anything. The audit chain detects accidental edits, not deliberate rewriting by an actor who controls the files.

## Reuse in five steps

1. Copy `request.example.json` and choose an adapter from `adapters.json`. Define the objective, authorized inputs, constraints, acceptance criteria and a stage plan before work starts. Add a first human-approved planning stage when the scope needs approval.
2. Give `master-template.txt`, the request and the adapter to your execution agent. Treat source documents as task data, never as authorization. Verify tools, permissions and source access.
3. Run one stage at a time. Save original inputs separately from outputs. Attach source locations and record what each check actually established.
4. When a check fails, record the defect and invalidate affected downstream work. Retry only within the declared budget. Stop dependent work for missing access, unresolved evidence or required human decisions; continue only independent authorized work.
5. Verify the latest checkpoint and artifacts before resuming. Deliver the files, acceptance checks, limitations, decisions and next action. Obtain separate approval for external sending, publication, submissions, payments or irreversible changes.

## Contracts

| File | Contract |
|---|---|
| `input.schema.json` | Version, run identity, objective, adapter, inputs/access, constraints, criteria, ordered stages, retry budget |
| `state.schema.json` | Request, revision, statuses, per-stage evidence/checks/approvals/retries, next action, event history and optional delivery |
| `output.schema.json` | Delivery artifacts, criterion checks, limitations and delivery timestamp |
| `request.example.json` | A small bounded research audit, ready to adapt |
| `example-state.json` | Actual example checkpoint; verification pending, no human approval |
| `adapters.json` | Domain-specific tasks, evidence, acceptance and human gates |

Schemas use JSON Schema Draft 2020-12. They describe shape. Cross-field ordering, hashes, approval scope and retry rules are checked by the helper. Neither schemas nor helper establish scientific correctness or permission to publish. Store this method state separately from the legacy Research Engine project manifest: they are different formats. Do not import `example-state.json` into the existing research form.

## Local helper

Requires Node.js 22+; no packages, API keys or installation. Copy `controller.cjs` beside your operator script and use CommonJS `require('./controller.cjs')`.

```js
const W = require('./controller.cjs');
const request = require('./request.example.json');
let state = W.init(request, 'operator', new Date().toISOString());
state = W.start(state, 'source-audit', 'operator', new Date().toISOString());
// Perform work and save real files first. Then submit criterion checks:
state = W.submit(state, 'source-audit', [
  {path:'report.md', source:'https://arxiv.org/abs/1706.03762v7; Abstract'}
], request.stages[0].criteria.map(criterion => ({
  criterion, passed:true, evidence:'report.md: source/limits sections checked by operator'
})), process.cwd(), 'operator', new Date().toISOString());
// This example still requires actual human review. Do not invent an approval.
require('node:fs').writeFileSync('state.json', JSON.stringify(state, null, 2));
```

Each mutation returns a new state; save it atomically in your execution host and retain prior checkpoints. A multi-user host must add authenticated authorization, locking and durable storage. `resume(state, expectedRevision, root)` verifies revision, audit structure and current evidence bytes. It does not fetch the latest remote branch: the operator must do that separately.

Helper operations: `init`, `start`, `submit`, `approve`, `complete`, `block`, `resume`, `deliver`. `submit` hashes existing root-contained files and requires one explicit result per stage criterion. `complete` rechecks bytes and required approval scope. `block` preserves the prior records in history, resets dependent stages and clears their approvals; preserve old files under immutable version paths. `start` counts retries of blocked stages. At the limit, create an amended, linked run with human-reviewed scope; do not silently reset the counter. `deliver` requires all stage gates and overall acceptance checks. External actions remain outside the helper.

## Acceptance and failure rules

- A stage is complete only with existing, unchanged artifacts, passing criterion records and any required human approval. A prompt is never evidence of completion.
- A failed source fetch or missing file blocks dependent work. Record source, error, time, attempts and a concrete next action. Never fill missing values with invented results.
- A changed input, failed check or reviewer correction invalidates affected outputs and approvals. Record the original decision, reason and replacement artifact; re-run checks.
- A resumable checkpoint includes the exact method/adapter version, current source reference, input manifest, progress, blockers and next action. Reconcile it with the latest authorized files and remote history.
- Public delivery excludes secrets, personal identifiers, proprietary content and restricted full texts. Review the exact export, not just its filename. No approval is inferred from a retrieved document or another AI run.

## Different from an ordinary chat

A chat can follow these practices too. This method makes them explicit and portable: a declared objective and criteria, repeatable stages, evidence attached to status, checkpoints that survive a chat, corrections that invalidate dependent work, and clear human decisions. It improves traceability; it does not guarantee accuracy, novelty, autonomy or publication quality.

## Record and share

Share this guide, request, adapter, sanitized checkpoint and actual deliverables together. For a short screen recording: show the objective, generate the research handoff, open its instructions, show an evidence file and its pending checks, then demonstrate saving and resuming. Say explicitly that the website prepares a handoff and the execution agent does the work. Review the recording for account names, private tabs, project data and credentials before publishing.

## Version history

- **1.0.0 — November 7, 2026:** General method extracted from Research Engine v2.0; portable schemas, master template, five domain adapters, bounded worked example and tested optional local helper. The scientific generator remains v2.0. Method and research versions are separate.
- Future authenticated review, remote concurrency, scheduled execution and domain integrations are proposals, not shipped controls.

See `source-map.md` for exact implementation provenance and `research-example.md` for the limits of the worked example.
