PM workflow

Modes

If the request does not identify a mode clearly, ask which outcome the user wants. NEVER guess between rewriting a document and reviewing it without changes.

Read only the selected mode contract. When preparing or accepting a specialist handoff, read that specialist’s brief, not its whole workflow:

• Researcher brief
• Writer brief
• Reviewer brief
• Review-synthesiser brief
• Product owner brief (Change check only)
• API estate reviewer brief and API package reviewer brief (API review only)

When the request already names the mode, read this workflow, the mode contract and every brief that mode uses in one parallel step, not one at a time. Review-only with more than one review: the reviewer and synthesiser briefs together, before the first dispatch.

Open a specialist workflow (researcher, writer, reviewer, review synthesiser, API reviewer) only to resolve a doubt the brief leaves.

API review: both reviewer briefs together, before the first dispatch. It reads component metadata only, so it needs no review context, preflight or page manifest.

A request that covers several documents follows the mode’s multi-document rules: confirm scope and cost first, skip documents that already have a current completed result, and keep per-document state minimal.

The shared output layout owns document keys and generated paths. The review-context contract owns optional approved context (backlog.md).

PM responsibility

The PM talks to the user, selects the mode, delegates, maintains state, and reports results. The PM does not research, draft, perform reviews or comparisons, or adjudicate review or product owner findings.

Generated tool files MUST link to these contracts instead of restating their rules. Never commit, push, publish, promote a draft, edit live page content, or clean generated history. In API review the PM also never edits component metadata, and never updates the API ledger.

Runtime commands

The PM runs only these commands:

• date -u +%Y-%m-%dT%H:%M:%SZ to capture Review-only run start and completion times and an Iterate review’s snapshot timestamp;
• SHA-256 checks required by review context, Review-only, and finalisation;
• node authoring-kit/scripts/preflight.mjs <source-path> [--context=<context-file>] (read-only) to resolve the document key, workspace, key collisions, research state, review-context paths, and routed rubric;
• node authoring-kit/scripts/init-review-run.mjs --source=<document> --count=<n> [--batch-id=<id>] to allocate a Review-only run;
• node authoring-kit/scripts/check-fresh.mjs --mode=review-only --source=<document> --count=<n> or node authoring-kit/scripts/check-fresh.mjs --mode=iterate --manifest=<run-manifest> --context-hash=<sha256:hash|null> (read-only) for the batch skip rule and the stale draft checks;
• node authoring-kit/scripts/build-api-estate-index.mjs [--slugs=a,b], node authoring-kit/scripts/check-fresh.mjs --mode=api-review --run=<run-dir>, node authoring-kit/scripts/merge-api-review.mjs --run=<run-dir> and node authoring-kit/scripts/summarise-api-review.mjs --run=<run-dir> for API review (the index script writes a new run directory and its inputs in the cache, the merge writes api-quality.json and the estate summary; none touches the ledger or component metadata);
• node authoring-kit/scripts/prepare-topic.mjs --topic=<slug> [--images=<path>[,<path>...]] for Exploratory research (read-only, except that --images creates the topic’s images/ folder and copies the user’s image files into it, never overwriting; it writes nothing else);
• node authoring-kit/scripts/check-review-report.mjs --report=<report.md> --source=<document> --started-at=<utc-timestamp> --role=<reviewer|synthesiser> [--context=<review-context.json>] [--enforce] for the mechanical report checks (warn-only: never pass --enforce yet);
• node authoring-kit/scripts/prepare-change-check.mjs --source=<document> [--base=<ref>] for Change check (it reads git without changing it, and writes only a new run directory in the cache: the base and proposed copies, the inventory and the report paths);
• node authoring-kit/scripts/summarise-batch.mjs --rows=<source>=<outcome>[,<source>=<outcome>...] (read-only) for the end-of-batch table;
• node authoring-kit/scripts/check-page-quality.mjs <iteration-path>;
• node authoring-kit/scripts/check-authoring-kit-manifest.mjs <manifest.json>;
• node authoring-kit/scripts/extract-component-api.mjs <slug>;
• node authoring-kit/scripts/update-manifest.mjs <subcommand> --flag=value ... (start-run, add-review, complete-run, close-run, start-iterate, add-iteration, finish-iterate): the only way to create or change a manifest, copy an accepted scratch report, or persist a Review-only snapshot. Each validates before it writes and prints one JSON object; the subcommands and flags are in the mode workflows;
• node authoring-kit/scripts/finalise-authoring-kit-draft.mjs --draft=<draft-path> --source=<source-path> --report=<report-path> --hash=sha256:<hex-digest>.

The scripts report; the PM decides. Each prints one JSON object. A script that exits non-zero with ok: false has found an error to correct or report, never to ignore. init-review-run.mjs creates an empty run directory in the cache, and update-manifest.mjs writes the manifests and accepted reports. The finaliser writes only what its own workflow defines.

The PM writes only the artefacts its selected mode workflow defines. In Exploratory research that includes a topic’s research-context.md, once, when it does not exist. In Iterate it also creates a missing backlog.md and research-context.md placeholder, and appends an entry to either only when a person asks (Context files). Deleting old run folders and promoted best drafts is a human step: the PM never does it or offers to. It never writes a manifest, copies a report, or builds JSON itself, and never reads a schema or an earlier run’s manifest to learn a format: update-manifest.mjs owns them.

See also