ship-readiness-orchestrator
Skill2 starsChanged 3 months agoMITView on GitHub
Use when the user mentions Shipworthy operationally; asks "are we shipworthy?", "are we shipready?", "is this shipworthy?", "shipworthy this", "check shipworthiness"; uses bare "shipworthy"; or asks for product/release readiness, full safe user-path audit, missing/overcomplicated UX paths, deployability, usability/design teardown, or making an app robust, clearer, simpler, beloved, viral, or effective.
In this repository4 other files it gives its agents.
- llms.txtllms.txt
- ship-deep-reviewSkill
- ship-product-workflowsSkill
- ship-workflow-claritySkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
49 rules. About 0 are common, 25 are distinctive, and 24 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈25
Distinctive · estimate
This author's own choices. Worth a look.
24
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 22
Use these skills as an ordered control stack:
- Very specific: line 24
REQUIRED CONTROLLER: Use ship-deep-review as the top-level controller for mission framing, waves, agent dispatch, the canonical claim …
- Very specific: line 25
REQUIRED PRODUCT LANE: Use ship-product-workflows as the product/runtime workflow lane for path discovery, safe user-path testing, state, …
- Very specific: line 26
REQUIRED CLARITY LANE: Use ship-workflow-clarity after path discovery or runtime tracing for orientation, state clarity, next-action …
- Distinctive: line 28
Do not run these as peer controllers.
- Distinctive: line 30
When lane skill instructions conflict with this orchestrator, apply the stricter safety, evidence, and synthesis rule.
- Distinctive: line 34
Before target analysis, agent dispatch, runtime testing, design critique, or final reporting:
- Very specific: line 36
Read this ship-readiness-orchestrator/SKILL.md completely.
- Distinctive: line 42
Do not infer these sub-skills from their names.
- Distinctive: line 50
If goal mode is available but explicit authorization is absent or ambiguous, ask once together with the multi-agent authorization ask when …
- Distinctive: line 54
Use that complete block verbatim as one message.
- Distinctive: line 86
When continuation is required, make Remaining Work the last substantive section and end the final response with the applicable two-question …
- Distinctive: line 88
Default or goal not yet active:
- Distinctive: line 106
Do not ask these questions in lane packets, commentary updates, or while the same turn is actively continuing.
- Very specific: line 112
Before frontier or finding synthesis, freeze every lane's original packet with capture_phase: pre_synthesis, its retained artifact_path, …
- Distinctive: line 125
After synthesis, require a one-to-one match from every original observation and execution receipt into the canonical ledger.
- Distinctive: line 133
Before closure, also require receipt/census-to-original reconciliation: execution receipts, runtime/static control censuses, and …
- Very specific: line 142
Only the renderer may transition a current full run from validating to complete.
- Very specific: line 165
Run scripts/render_report.py over the reconciled ledger before verifier approval and again before HTML rendering.
- Distinctive: line 181
Do not create a parallel receipt inventory.
- Distinctive: line 185
Use one designated runtime driver per browser/server instance.
- Distinctive: line 209
Before dispatching agents, writing findings, or judging design quality:
- Distinctive: line 211
Read the full user request and all target-defining files, screenshots, URLs, docs, or local instructions.
- Distinctive: line 215
Treat the run as read-only unless the user explicitly authorizes the exact action and a verified non-production reset/sandbox contract …
- Very specific: line 231
If the current user request already explicitly authorizes parallel subagents, delegation, or multi-agent work, such as "Run Shipworthy full …
- Distinctive: line 271
Treat the initial render as a draft projection.
- Distinctive: line 280
Treat the verified canonical ledger as immutable during this report critique.
- Very specific: line 286
If the critique finds a mismatch, correct the canonical projection input or the deterministic rendering path, rerun validation, and …
- Distinctive: line 300
If agent tooling is unavailable, unsafe, too overlapping, or not explicitly authorized, run the lanes sequentially in the main session and …
- Very specific: line 316
Before collection, read references/coverage-manifest.md, references/evidence-state.md, references/schemas/readiness-ledger.schema.json, and …
- Distinctive: line 332
Write to the ledger at these gates:
- Very specific: line 349
Run the Goal Mode Persistence Gate.
- Distinctive: line 351
Run the Flagship Frontend Path-Walk Gate.
- Very specific: line 358
Run the Adaptive Exhaustion Gate after each wave: update candidate inventories, manifest, frontier burn-down, and new candidate IDs.
- Distinctive: line 365
Run a fix-cascade check on major recommendations: compare against the no-change baseline, identify what the fix could break downstream, and …
- Very specific: line 395
Read references/lane-prompts.md before dispatching product, clarity, design, verifier, or release-gate lanes.
- Very specific: line 396
Read references/browser-evidence-routing.md before native browser, computer-use, or Playwright work.
- Very specific: line 397
Read references/host-execution-recipes.md before invoking target-owned execution.
- Very specific: line 398
Read references/ledger-validation-contract.md before structured render or import.
- Very specific: line 399
Read references/evidence-import-contract.md only for browser, Playwright, or legacy structured input.
- Very specific: line 400
Read references/coverage-manifest.md, references/evidence-state.md, and ship-product-workflows/references/path-discovery-and-coverage.md …
- Very specific: line 401
Read references/final-report-contract.md before writing the final report or roadmap.
- Very specific: line 402
Read references/archetype-overlays.md when the target matches a known product archetype (checkout, auth, ai-chat, dashboard, …).
- Very specific: line 403
Read references/changed-scope.md for a delta / in-session re-audit ("is my change ready?"): scope to the changed surface plus its blast …
- Very specific: line 404
Read references/visual-html-report.md for every operational Shipworthy invocation.
- Very specific: line 406
Read references/pressure-tests.md when validating or forward-testing this skill, or when the user asks whether the orchestration is strong …
- Distinctive: line 424
Do not implement fixes unless the user explicitly asks for implementation after the review.
- Very specific: line 426
Only when the audit is truly finished and no continuation handoff is required, end an operational Shipworthy final answer that contains …
- Distinctive: line 457
Only testing paths that exist and missing reasonable user goals that have no UX path.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Shipworthy Readiness Orchestrator
Core Promise
Run a repo-agnostic, evidence-heavy product readiness investigation that combines Deep Review, product workflow QA, and workflow clarity/design critique without creating competing truth layers or overclaiming readiness. Default invocation means maximum safe discoverable coverage: build a capped parallel lane roster when agents are available, map reasonable user intents, detect missing UX paths, test every safely testable path that can be reached within the declared boundary, judge path effort and design quality, then prove before proclaiming.
Shipworthy Invocation Contract
Any operational mention of shipworthy triggers this orchestrator in full blast unless the user explicitly narrows scope, asks for a rapid/narrow/static pass, or is clearly discussing the Shipworthy skill system itself rather than asking to audit a target. The canonical trigger phrase is "are we shipworthy?". Equivalent triggers include shipworthy, is this shipworthy?, shipworthy this, make this shipworthy, check shipworthiness, and readiness variants such as are we shipready?.
If no target is obvious, still treat the invocation as a Shipworthy run: complete the Sub-Skill Load Gate, then ask for or infer the target as the first Start Gate item. Do not silently downshift to a generic chat answer just because the trigger was short.
A full Shipworthy invocation is not a quick pass. Full blast means source-backed discovery of the bounded safe path universe, actual frontend execution, mandatory multi-wave evidence gates, adaptive continuation while safe work remains, persistent goal-mode execution when the platform and user authorization allow it, and a mandatory HTML report generated from the final ledger. If the candidate inventories, coverage manifest, path_frontier, coverage matrix, verifier certificates, evidence debt register, goal-mode status, and HTML report path are missing, the run is incomplete.
Required Sub-Skills
Use these skills as an ordered control stack:
- REQUIRED CONTROLLER: Use
ship-deep-reviewas the top-level controller for mission framing, waves, agent dispatch, the canonical claim ledger, coverage matrix, evidence debt, verifier gates, and final synthesis. - REQUIRED PRODUCT LANE: Use
ship-product-workflowsas the product/runtime workflow lane for path discovery, safe user-path testing, state, persistence, forms, navigation, permissions, backend symptoms tied to user-visible paths, responsive checks, accessibility smoke, and product evidence packets. - REQUIRED CLARITY LANE: Use
ship-workflow-clarityafter path discovery or runtime tracing for orientation, state clarity, next-action clarity, consequence and non-consequence clarity, recovery, trust/proof/governance, accessibility visibility, expert controls, design critique, and harmful simplification warnings.
Do not run these as peer controllers. Use one canonical Deep Review evidence state. Product workflow and clarity work feed packets into that state, inheriting prior evidence instead of re-deriving or double-counting it.
When lane skill instructions conflict with this orchestrator, apply the stricter safety, evidence, and synthesis rule. Lane wave patterns are lane-local evidence collection only; Deep Review owns wave barriers, verifier gates, summaries, readiness language, and final synthesis.
Sub-Skill Load Gate
Before target analysis, agent dispatch, runtime testing, design critique, or final reporting:
- Read this
ship-readiness-orchestrator/SKILL.mdcompletely. - Resolve and read the full
SKILL.mdforship-deep-review. - Resolve and read the full
SKILL.mdforship-product-workflows. - Resolve and read the full
SKILL.mdforship-workflow-clarity. - If a sub-skill cannot be found or read, report it and continue as a bounded standalone audit using this skill's local references. Record the missing lane and lost independent coverage as evidence debt, keep the mandatory HTML report, and do not claim full multi-lane Shipworthy coverage.
Do not infer these sub-skills from their names. Do not dispatch a product or clarity lane before the matching sub-skill body has been read.
Goal Mode Persistence Gate
For every full Shipworthy invocation, after the Sub-Skill Load Gate and before the Multi-Agent Authorization Gate, check whether the current platform offers persistent /goal mode, a goal tool, or an equivalent long-running objective mechanism. Do not imply that Shipworthy instructions override platform goal-mode policy; platform/tool policy wins.
If the current user request invokes /goal, says to use goal mode, asks for persistent goal mode, or explicitly authorizes goal persistence, start or continue a persistent Shipworthy goal when the platform exposes that capability and policy allows it. Use an objective such as: "Complete the full Shipworthy audit for <target>, including safe frontend path-walking, path_frontier closure, adaptive exhaustion, verifier gates, mandatory HTML report, and canonical recovery that can resume unfinished waves after an authorized capability failure." The goal objective must require the controller to reread the active goal and orchestration checkpoint after compaction, resumption, or controller replacement. Record goal_mode_status, the objective, and whether the platform goal is active in the ledger and Orchestration Checkpoint.
If goal mode is available but explicit authorization is absent or ambiguous, ask once together with the multi-agent authorization ask when multi-agent authorization is also absent:
Shipworthy full blast is a long-running audit. Recommended: reply yes to authorize persistent goal mode and parallel subagents for this Shipworthy run. If authorized, I will complete every required wave and verifier gate, use every applicable safe alternative when a capability fails, resume unfinished work from the checkpoint, and produce the final HTML report. The goal will not be marked complete while required work remains unfinished; any terminal limitation will identify what remains unfinished and why.
Use that complete block verbatim as one message. Do not shorten it, split it, paraphrase it, or substitute an older authorization sentence.
If the previous assistant message asked the combined authorization question and the user replies yes, yes for both, authorized, or equivalent, treat that as explicit authorization for both persistent goal mode and parallel subagents. In Codex, when a goal tool is available and platform policy allows it, create or continue the persistent Shipworthy goal before lane dispatch, then record goal_mode_status: active or the platform-specific result. If goal creation fails or is unavailable, record goal_mode_status: unavailable or goal_mode_status: failed and continue with a goal-equivalent resumable ledger; if subagent dispatch is unavailable despite authorization, record the dispatch limitation separately.
If the platform has goal mode but authorization is denied, unavailable, or not received after the gate question, record goal_mode_status: not_authorized and continue with a goal-equivalent resumable ledger. If the platform has no goal mode, record goal_mode_status: unavailable and continue with the same goal-equivalent resumable ledger. Goal-mode fallback is orchestration debt, not a reason to skip frontier closure, verifier gates, or the HTML report.
Completion State Gate
Keep operational lifecycle, coverage qualification, and release decision separate. In orchestration-checkpoint.json, record audit_status as active, complete, blocked, or user_stopped; keep goal_mode_status for goal availability/authorization; and record goal_completion_status as active, complete, blocked, user_stopped, or not_applicable. In path_frontier, record finality: open|exhausted, remaining_safe_work, and resume_conditions. In the ledger, use readiness_disposition only for ready, conditionally_ready, not_ready, or cannot_determine. An audit can complete with not_ready; a confirmed defect is not unfinished audit work.
Before claiming closure, reconcile candidate source extracts, control_census_paths, zero_yield_pass_ids, raw outputs, evidence-debt actions, recovery/failover state, and validation receipts through scripts/render_report.py. The orchestrator must not mark the persistent goal complete unless that final gate succeeds with audit_status: complete, a complete ledger, a closed multi-source frontier, full frontend path-walk, approved verifier, source-backed inventory/census reconciliation, qualifying zero-yield passes, a renderer-issued completion receipt, and no active recovery. A complete audit may still be not_ready and retain a terminal blocked recovery; a truthful active, blocked, or user_stopped audit still receives the mandatory HTML report but is not full closure.
For a current run_scope: full, this gate also requires three distinct
verified wave IDs and retained independent certificates, raw-to-final discovery
reconciliation, an apparent-affordance census, exact route/role/state/viewport/
surface/control/input/before-after execution receipts, retained verifier output
and citation provenance, frontend-to-backend correlation for backend-effecting
controls, recovery exhaustion, canonical artifact validation, and the mandatory
HTML report. Positive recent yield keeps discovery active;
small targets and strong findings never waive these controls. Closure is
derived from retained receipts, not authored by a report builder.
Incomplete-Run Continuation Gate
Before every user-facing final response, derive a Remaining Work register from the canonical frontier, candidate-inventory differences, evidence debt, omitted gates, failed capabilities, remaining_safe_work, and resume_conditions. Do this even for a truthful active, blocked, user_stopped, downgraded, or otherwise constrained report. Never replace exact remaining rows with “and more,” “other paths,” or a count-only summary.
This is an inline-chat requirement. Put the Remaining Work summary and the two questions directly in the assistant's user-visible final response. The HTML report, ledger, remaining-work.json, an attachment, or a link may provide the exhaustive detail, but none of them satisfies or replaces the inline chat handoff. The inline response must still name exact grouped counts, every unresolved category, the next frontier batch, the exhaustive artifact path when used, and the applicable two-question block.
The register must account for every material row that is sampled_with_justification, blocked, avoided, evidence_debt, unattempted, unknown, or maybe; every unresolved inventory difference and evidence-debt item; every omitted required gate; and every named resume condition. For each item show its stable ID or semantic key, status, owner, reason/blocker, next action or proof needed, and resume condition when applicable. If the inline list would be unwieldy, write a complete remaining-work.json beside the report, link it, and show exact grouped counts plus the next frontier batch inline; the artifact must contain every item.
The continuation ask is mandatory whenever the audit is not truly finished. “Truly finished” means audit_status: complete, path_frontier.finality: exhausted, closure_state: closed_multi_source, no unfinished statuses above, no unresolved inventory differences or evidence debt, no omitted required gate, full required frontend proof, approved verification, and successful report validation. A completed not_ready audit with fully resolved coverage may skip the continuation ask and use the fix handoff instead: confirmed defects are known outcomes, not unfinished audit paths.
When continuation is required, make Remaining Work the last substantive section and end the final response with the applicable two-question block below. Put no user-facing prose, citations, or generic closing after it; host-required machine directives may follow.
Default or goal not yet active:
Would you like me to continue through every remaining safe, authorized path and proof item?
Would you like me to make that continuation a persistent goal so it resumes from the saved checkpoint until the frontier is exhausted?
Goal already active:
Would you like me to continue through every remaining safe, authorized path and proof item under the active goal?
Should I keep the persistent goal active and resume from the saved checkpoint until the frontier is exhausted?
Goal mode unavailable or failed:
Would you like me to continue through every remaining safe, authorized path and proof item?
Persistent goal mode is unavailable here; would you like me to use the resumable checkpoint as the goal-equivalent and continue until the frontier is exhausted?
Do not ask these questions in lane packets, commentary updates, or while the same turn is actively continuing. Lane packets return the complete unresolved register to the orchestrator. The gate applies when yielding a user-facing final response.
Raw-Evidence-to-Ledger Reconciliation Gate
Original-Evidence Closure Gate
Before frontier or finding synthesis, freeze every lane's original packet with
capture_phase: pre_synthesis, its retained artifact_path, observations,
and execution_receipts. Those observations are the input to synthesis: they
must not be reconstructed from path_frontier, findings, the canonical ledger,
checkpoint summaries, report input, or HTML. Do not put terminal dispositions
or downstream PF-*/FND-* identities into an original packet. That is
circular provenance and must fail closure.
Capture continuously: Observe → append → verify → continue. After each bounded behavior, append its observation and receipt to the retained packet, verify the write, then exercise the next behavior. Do not reconstruct a whole wave from memory after exploration.
After synthesis, require a one-to-one match from every original observation and execution receipt into the canonical ledger. Original fields remain unchanged; the ledger adds exactly one terminal disposition. Any original observation missing from the ledger, ledger observation without an original source, changed observation, missing receipt, or material before/after change without exact transition lineage fails the gate. No verifier approval, wave completion, zero-yield pass, blocked status, or report prose can waive it.
Before closure, also require receipt/census-to-original reconciliation:
execution receipts, runtime/static control censuses, and action-signalling
affordances must each resolve to the frozen original packet before that packet
resolves to the ledger. On failure, consume the renderer's bounded
machine-readable repair queue, repair preserved evidence or safely re-exercise
the named path, set validation back to validating, and rerun the same
renderer. After three failed attempts, stop as blocked with explicit evidence
debt; never loop indefinitely or call the audit complete.
Only the renderer may transition a current full run from validating to
complete. It must retain a renderer-issued completion receipt binding the
report input, checkpoint, original packets, and final HTML digests. Missing or
stale receipt proof invalidates completion. Hand-authored HTML, verifier prose,
and a checkpoint assertion cannot substitute for this receipt.
The ledger remains a draft until every material observation from raw lane and verifier packets, execution receipts, runtime/static control censuses, the apparent-affordance census, and source-promised missing paths has exactly one terminal disposition: a frontier row, finding, evidence-debt record, evidence-backed rejection, or reasoned out-of-scope record. A material observation must not silently disappear.
Normalize each raw observation with a stable ID, source kind, evidence refs, semantic key, and behavioral identity. Reconcile route, role, state, viewport, containing surface, control identity/type, input mechanism, and before/after state. Wording aliases may match when those behavioral dimensions agree; a wrong semantic variant must fail. Do not let desktop satisfy mobile, member satisfy admin, opening a surface satisfy its controls, or one transition satisfy another. Give independently fixable behavior classes distinct finding lineage—for example, misleading success feedback and reload data loss are not one defect.
Run scripts/render_report.py over the reconciled ledger before verifier
approval and again before HTML rendering. If retained raw evidence proves an
omission or mis-keyed variant, amend the same ledger, increment its revision,
preserve the raw evidence, and renew verifier approval. If proof is still
missing, add an explicit frontier/evidence-debt disposition and keep closure
incomplete. Incomplete or blocked status never bypasses this reconciliation;
it changes the verdict, not the accounting requirement. Never invent execution
merely to make reconciliation pass.
Frontend-to-Backend Correlation Gate
For each material control whose user-visible action should change backend state
or truth—save/create/update/submit, import/export, publish, invite, auth or
permission changes, safe destructive/recovery/asynchronous actions, and success
or failure feedback—extend its existing execution receipt with
backend_effect_expected, a reason, and one nested backend_correlation.
Do not create a parallel receipt inventory. The control receipt owns the
correlation; its transition receipt retains before/after lineage without
double-counting the same action.
Use one designated runtime driver per browser/server instance. Capture the
backend process to a fresh external run log when authorized, then for each
backend-effecting action record the pre-action offset/state, exercise the UI,
capture request/response and console evidence, read only the new log range,
inspect authorized resulting state, perform reload/re-entry when persistence is
claimed, and append the receipt immediately. Canonical correlation status is
matched, mismatch, blocked, or not_applicable; every network, logs,
state, and reentry channel is explicitly observed, blocked, or
not_applicable.
matched requires bounded runtime backend evidence. Success with a failed or
duplicate mutation, unchanged state, correlated unhandled error, or failed
re-entry is mismatch with finding lineage. An unavailable channel is
blocked/NOT_PROVEN, not a failure and not a pass. Purely presentational
controls may be not_applicable with a reason. Try, in order, browser network
evidence, an authorized local API/state endpoint, existing target-owned tests
or telemetry, and already-accessible authorized provider logs. Never install
monitoring, alter production instrumentation, request credentials, access an
unauthorized store, retain secrets/bodies/personal data/unbounded logs, or use
source as runtime proof. This gate follows the existing safe-test boundary and
does not expand into a backend architecture review.
Start Gate
Before dispatching agents, writing findings, or judging design quality:
- Read the full user request and all target-defining files, screenshots, URLs, docs, or local instructions.
- Read target repo/app instructions and source-of-truth docs when present and target-relevant:
AGENTS.md,CLAUDE.md, README, architecture docs, product docs, test docs, deploy docs, package scripts, or equivalent. If the target is only a supplied static artifact, screenshot set, paste, or scenario, do not treat the ambient working directory as target truth unless the user explicitly connects it. - Record the target fingerprint: repo path, branch, commit, dirty state, worktree, runtime URL or launch command, environment, timestamp, account/role/fixture, viewport/device assumptions, and evidence output location.
- Define the safe-test boundary: allowed actions, forbidden actions, mutation risks, reset plan, privacy constraints, paid/provider constraints, production risks, and stop conditions.
- Treat the run as read-only unless the user explicitly authorizes the exact action and a verified non-production reset/sandbox contract exists. A disposable fixture alone does not grant authority. High-risk actions require action-level approval plus the verified boundary.
For a declared full benchmark/comparative fixture only, require a clean
git status --porcelain before exploration, record the baseline revision/tag,
and write all generated evidence directly under the external Shipworthy run
root. Pre-existing screenshots, logs, receipts, ledgers, snapshots, or any other
dirty entry abort the benchmark before analysis; do not delete user files
without authorization. Use a clean clone/worktree or obtain explicit cleanup
authorization. Still render the mandatory blocked HTML explaining the aborted
preflight, but do not issue benchmark results. Ordinary product audits preserve
and record dirty worktrees and do not inherit this benchmark-only abort rule.
Multi-Agent Authorization Gate
For every full Shipworthy invocation, after the Goal Mode Persistence Gate and before lane dispatch or sequential fallback, check whether the current platform's agent tooling requires explicit user authorization for subagents, delegation, or parallel agent work. Do not imply that Shipworthy instructions override platform tool policy; platform/tool policy wins.
If the current user request already explicitly authorizes parallel subagents, delegation, or multi-agent work, such as "Run Shipworthy full blast with parallel subagents authorized", record that authorization in the ledger and proceed to the multi-agent lane roster when safe.
If authorization is absent or ambiguous in the current user prompt, this is not yet a denial and not yet "not received." The next response must ask the authorization question and stop. Do not continue target analysis, tool work, lane planning, or sequential fallback in the same response. Do not say you are proceeding sequentially before the authorization question has been asked. If the Goal Mode Persistence Gate also needs authorization, ask the combined question from that gate. Otherwise ask exactly:
Shipworthy full blast is designed to use parallel subagents for independent product, clarity, release, accessibility, state, and verifier lanes. Do you authorize parallel subagents / delegation / multi-agent work for this Shipworthy run?
Only dispatch subagents after the user explicitly authorizes parallel subagents, delegation, or multi-agent work. Not received means the user failed to answer after the authorization question was asked, not merely that the original request lacked authorization. If authorization is denied, unavailable, or not received after the gate question, run the same lane roster sequentially and record "sequential fallback because multi-agent authorization was not granted" in the ledger, Orchestration Checkpoint, evidence debt / orchestration debt, and final report. Do not treat sequential fallback as equivalent to independent multi-agent coverage.
Flagship Frontend Path-Walk Gate
For every full Shipworthy invocation, after the Multi-Agent Authorization Gate and before source-heavy analysis, run the Flagship Frontend Path-Walk Gate. Repeat this commitment before starting work:
I will run the full flagship Shipworthy audit unless you explicitly narrow scope. That means I will use the actual frontend through browser, in-app browser, Chrome, Playwright, or Computer Use when available; interact like a human; map the path universe; attempt every safe discoverable user path; record blocked, avoided, unsafe, and unavailable paths as evidence debt; and use source, CLI, HTTP, tests, logs, and docs as supporting evidence, not as a substitute for frontend path-walking. If I cannot perform actual frontend path-walking, I will label the result conditional, static, or limited, not a full Shipworthy run.
Actual frontend path-walking is required for a full flagship run when a runnable UI, hosted app, local dev server, browser-hosted prototype, desktop app, Chrome session, in-app browser surface, or Computer Use target is available. Human-style frontend evidence means action sequences through the product UI with observed screens/states and artifacts such as screenshots, DOM/UI/accessibility snapshots, console/network traces, recordings, or Computer Use screenshots.
Read references/browser-evidence-routing.md before selecting a frontend tool. Use the host's native browser or computer-use capability by default for adaptive exploration. Use an existing target-owned Playwright setup only for deterministic replay, explicit assertions, isolated contexts, traces, cross-browser checks, or CI regression proof. Record the selection and its proof boundary in the ledger; the tool choice never changes the canonical proof or verifier rules.
Browser Failover Gate
Every controller or lane prompt that authorizes browser access must carry the Browser Failover Contract and Block-Recovery Ladder from references/browser-evidence-routing.md. A browser or agent failure does not end its wave. Preserve the unfinished frontier, apply the bounded recovery ladder, and resume the unfinished wave from the checkpoint when recovery succeeds. Supporting source, CLI, API, tests, and logs may explain the failure but never substitute for required frontend execution. Keep recovery active while an applicable safe authorized alternative remains; use blocked only after the final capability inventory proves exhaustion, and use user_stopped only when the user stops the run.
In particular, do not stop the lane before attempting already available independent Playwright; control through the same locked native-browser binding is not independent Playwright.
Shipworthy operates through the four public skills and their skill-owned resources. Continue to route and report through those skills without requiring another product surface.
Source, CLI, HTTP, tests, logs, docs, Railway/provider checks, and database probes are supporting evidence, not as a substitute for frontend path-walking. Use them to find routes, explain symptoms, verify backend causes, and support release gates, but do not let them replace the actual product walk.
If no actual frontend path-walking occurred, the result is not a full Shipworthy run. Label it as bounded conditional audit, static constrained pass, changed-only pass, or source/CLI readiness audit, record the downgrade reason, and do not use full flagship language. The final report must include frontend path-walk status, frontend tool, runtime target, path-walk status, and downgrade reason when applicable.
HTML Report Gate
Every operational Shipworthy invocation must produce a self-contained HTML readiness report from the final ledger, regardless of whether the run is full flagship, conditional, static constrained, changed-only, source/CLI-only, or downgraded. Downgrade status changes the report contents and verdict language; it does not remove the report requirement.
Generate canonical readiness-ledger.json, report-input.json, and readiness-report.html from the final ledger after verification; keep orchestration-checkpoint.json beside report-input.json as separate operational proof. Do not create a redundant readiness-report.json. Default to ~/.shipworthy/runs/<target-slug>/<timestamp>/ so the audited repo stays read-only. Use repo-local .shipworthy/reports/<timestamp>/ only when the user explicitly requests repo artifacts or the target's instructions require repo-local audit artifacts.
Before final response, verify that readiness-report.html exists, was rendered from the final ledger/report JSON, and is linked in the final answer. If report generation fails, file writes are impossible, or the user explicitly forbids artifact creation, lead the final answer with HTML report: MISSING/BLOCKED, explain why, record it as deliverable debt, and do not imply the Shipworthy run is complete.
Ledger-to-HTML Critique and Revision Gate
Treat the initial render as a draft projection. Before delivery, compare it
against the canonical ledger and checkpoint for relevant data loss, distorted
meaning, or unsupported additions. Confirm that it preserves every formal
finding, affected semantic paths, every evidence-debt record and its exact proof_needed,
canonical closure and omission language, execution receipts,
and rejected and out-of-scope discoveries. Spot-check every action class:
Passed / Keep preserves working behavior, Skip preserves the safety or scope
boundary, and neither receives synthesized corrective language.
Treat the verified canonical ledger as immutable during this report critique. A report mismatch is a projection or renderer defect; do not change the ledger to make the HTML pass. Reopen the ledger only when retained raw evidence independently proves that the ledger itself is wrong, then record a new ledger revision and renew verifier approval before rendering again.
If the critique finds a mismatch, correct the canonical projection input or the
deterministic rendering path, rerun validation, and overwrite the same readiness-report.html.
The agent must not hand-edit the HTML, create a second
“improved” report, invent missing ledger content, or deliver both versions.
Repeat this bounded critique-and-revision gate until the same
readiness-report.html aligns with the ledger or fail closed as
HTML report: MISSING/BLOCKED.
Full-Blast Agent Rules
For a full readiness run, use agents when the platform exposes agent tooling, the work decomposes into independent non-overlapping lanes, and the Multi-Agent Authorization Gate has explicit authorization. Before launch, write a lane roster with each lane's scope, excluded overlap, required sub-skill body, expected output packet, evidence artifact location, safe-test boundary, and multi-agent authorization status. Each lane prompt must require reading the applicable SKILL.md body before acting. The final report must include or point to this roster; otherwise the full-blast run is incomplete.
- Codex: run at most 6 concurrent specialist agents; close completed agents after their outputs are read.
- Claude Code: launch all independent wave agents at once when there are 13 or fewer and scopes do not conflict; prefer fewer lanes when the target is small or scopes overlap.
- If agent tooling is unavailable, unsafe, too overlapping, or not explicitly authorized, run the lanes sequentially in the main session and record the limitation as evidence debt / orchestration debt in the final report. Do not pretend a sequential pass had independent-agent coverage.
- Agents parallelize discovery, route inventory, design critique, release gates, state/API tracing, role/permission checks, disconfirmation, and verification. The orchestrator owns the canonical ledger and runtime execution plan.
- For one shared runtime, use a single coordinated runtime driver by default. Multiple agents may drive the live app only when isolated users, resettable fixtures, disposable data, independent browser profiles, or read-only surfaces make the evidence safe and non-conflicting. Otherwise agents return path plans and evidence packets while the orchestrator or one designated runtime lane performs coordinated clicking.
Full-Blast Wave Contract
Full blast requires a minimum of three verified waves after Wave 0 preflight: broad reconnaissance, targeted deep dive, and release-gate / what-did-we-miss. This is a minimum of three verified waves, not a maximum. Every wave summary requires the Deep Review read-all, evidence-state, independent-verifier, verification-certificate, and drift-check gate.
Use adaptive continuation after Wave 3 when coverage is not closed and safe authorized available work can still improve it. Continue with additional waves for unresolved major route families, user roles, state variants, runtime proof, contradictions, high-severity disconfirmation, safe path attempts, or evidence debt, or when the verifier objects that coverage is too thin. Do not end a full blast because three waves happened; exhaust it when no safe authorized available action can improve the evidence, then report either complete coverage or the exact constrained qualification and decision.
Path-universe accounting is mandatory. Read references/coverage-manifest.md and build source-backed candidate inventories before execution. Every material candidate must map to a canonical row labeled covered, sampled_with_justification, blocked, avoided, missing, out_of_scope, or evidence_debt before final readiness language is written. unattempted, unknown, and maybe remain nonterminal. Do not use sampled or inferred in a full frontier. Treat all safe discoverable paths inside the declared boundary as the coverage ambition; do not substitute a few happy paths, top tasks, or agent consensus.
Adaptive Exhaustion Gate
For a full flagship Shipworthy run, create a Path Frontier Ledger named path_frontier before quality judgment. The path_frontier is stricter than the coverage summary: it is the live queue of every material expected user intent, discovered route, screen, control, role, state variant, device/input variant, integration, and safe action that could change the readiness verdict.
Before collection, read references/coverage-manifest.md, references/evidence-state.md, references/schemas/readiness-ledger.schema.json, and ship-product-workflows/references/path-discovery-and-coverage.md. Maintain one canonical path_frontier using the readiness-ledger schema; do not accept an ad hoc list or a second frontier shape from a lane.
Path frontier sources must include runtime crawl, visible UI, routes, components, APIs, docs, tests, fixtures, roles, states, device variants, and expected human intents. Apply the Human-Tester Matrix: first-time user, confused user, impatient user, returning stale-state user, mobile user, keyboard-only user, empty/loading/error states, permission mismatch, guest/member/admin where applicable, and the intent families create, edit, delete/cancel, recover, invite/share/export/import, settings/account, onboarding, failure recovery, payment/auth where applicable.
Each path_frontier row must use versioned semantic lineage from intent through feature, surface, control, and transition; record observations from canonical method families; carry attempt/evidence proof; and name an owner lane when material. Candidate inventories must retain raw locators and map one-to-one into the frontier; copying frontier keys into a census is circular and does not prove coverage. Valid terminal statuses are covered, sampled_with_justification, blocked, avoided, missing, out_of_scope, and evidence_debt.
Affirmative readiness is forbidden while any material path_frontier row remains unattempted, unknown, or maybe. Continue after the minimum three waves while finality: open. Exhaustion requires every material row to have a terminal status, runtime/static/declared candidate inventories to reconcile, and two qualifying zero-yield discovery passes from distinct canonical method families to find no new raw candidates. Before final synthesis, run a verifier pass asking "what plausible paths were missed?" If that pass names a plausible material path, add it to the candidate inventory and frontier, then continue or report a constrained decision. A proven missing path or tested failure produces not_ready; it does not keep the audit operationally active.
Use adaptive effort floors and caps to prevent shallow exits without wasting tiny targets: tiny targets close the frontier or spend 10-20 minutes / 15-30 meaningful attempts; small targets close the frontier or spend 30-45 minutes / 40-80 meaningful attempts; medium targets close the frontier or spend 60-90 minutes / 100-200 attempts; large targets may need multi-session frontier burn-down. Time or attempt count alone never proves completion.
If a safe authorized available action remains, keep finality: open, set exhaustion_status: incomplete, list the next frontier batch, and continue or persist a resume checkpoint. When no safe authorized available action can improve coverage, use finality: exhausted, retain exact resume conditions and terminal dispositions, reconcile the evidence, and render the HTML report. The audit may finish not_ready or cannot_determine; only affirmative readiness requires fully proven coverage.
Ledger Protocol
Before lane dispatch, path testing, verifier work, or summary-writing, establish one canonical evidence state owned by the orchestrator. If a writable evidence location exists, record the ledger path or artifact location; otherwise maintain the ledger explicitly in working notes and include its inline snapshot in the final report. Lane agents return raw packets; they do not write the canonical ledger directly.
Write to the ledger at these gates:
- Target fingerprint and safe-test boundary.
- Lane roster and planned evidence locations.
- Expected intents, missing-path candidates, and path universe.
- Each path attempt or safe trace, immediately after observation.
- Each lane output after the orchestrator reads it in full and normalizes severity, confidence, provenance, and coverage labels.
- Verifier decisions: approved, downgraded, rejected, needs-proof, blocked, and required retargeting.
- Fix-cascade notes for major recommendations.
- Final drift check and final disposition of evidence debt.
Every material claim, missing path, blocked check, avoided check, rejected claim, false positive, recommendation, and readiness statement must map to a ledger row or explicit evidence gap. Do not use a narrative paragraph as a substitute for a ledger write. Do not delete inconvenient rows; update status and final disposition.
Mandatory Flow
- Complete the Sub-Skill Load Gate.
- Route the run as a full Deep Review unless the user explicitly asks for a rapid or narrow pass.
- Run the Goal Mode Persistence Gate. If
/goal, persistent goal mode, or goal authorization is explicit and platform policy allows it, start or continue that goal; otherwise recordgoal_mode_statusand use a goal-equivalent resumable ledger. - Run the Multi-Agent Authorization Gate for full Shipworthy invocations. If explicit authorization is already present (for example, "Run Shipworthy full blast with parallel subagents authorized"), record it and continue. If authorization is absent or ambiguous, ask the authorization question and stop before deciding multi-agent dispatch vs sequential fallback. Do not continue sequentially in the same response.
- Run the Flagship Frontend Path-Walk Gate. Identify the actual frontend target and tool plan before source-heavy analysis. If actual frontend path-walking is impossible or explicitly out of scope, downgrade the run label immediately and record why.
- Route
ship-product-workflowsasmajorfor broad readiness, defaulting toaudit_allplusaudit_top_tasksplusaudit_high_risk. Downshift only when the user explicitly asks for a rapid/narrow pass, the target is genuinely small/static-only, actual frontend path-walking is impossible, or safe-test boundaries make full coverage impossible. Ifaudit_allis not feasible, still map the whole discovered path universe and label every pathcovered,sampled_with_justification,blocked,avoided,missing,out_of_scope, orevidence_debt. For a delta / in-session re-audit ("is my change ready?"), run changed-scope mode perreferences/changed-scope.md: scope to the changed surface plus its blast radius, mark untouched pathsout_of_scope, and keep the verdict scoped to the change rather than the whole product. - Read
references/evidence-state.mdand initialize the canonical evidence state before lane roster, dispatch, path testing, or summaries. Record target fingerprint, safe-test boundary, ledger location or inline-ledger plan, goal_mode_status, multi-agent authorization status, frontend path-walk status, first evidence debt rows, and initial claim/coverage/debt/frontier table headers. - Read
references/lane-prompts.mdand build a concrete lane roster before dispatch: product/runtime path QA, workflow clarity/design critique, release/deploy gates, accessibility/responsive smoke, data/state/persistence, role/permission, and verifier lanes as applicable. Keep scopes independent and non-overlapping. Write the roster, goal_mode_status, multi-agent authorization status, frontend tool plan, and path-walk status to the ledger. - Launch the first wave of specialist agents according to the Full-Blast Agent Rules only if explicitly authorized. Give every lane the target fingerprint, safe-test boundary, evidence-state contract, required sub-skill body to read, exact scope, excluded scope, output packet format, frontend path-walk requirement, path_frontier additions requirement, and proof limits. If agents cannot be launched, or authorization was denied/unavailable/not received, record why and run the same lane roster sequentially.
- Execute the mandatory sequence in
references/coverage-manifest.md: freeze declared/static/runtime candidate inventories with raw locators and digests; map each candidate exactly to one canonical frontier row or retained difference; walk safe spawned surfaces to a fixpoint; reconcile lifecycle, role, state, viewport, input-mode, recovery, and persistence variants; then run independent negative inventory passes. Build the material-state control census as supporting evidence, never by copying frontier keys and never as omission proof. Treat "try every single path" as every safe discoverable path in the bounded union of those inventories, with honest reasons and debt for anything unsafe or unavailable. Archetype overlays add provenance-tagged hypotheses to the declared inventory, never passes. - Execute every safely testable discovered path inside the declared boundary through the actual frontend when available. Exercise every safe material control once per materially different behavior and record before/after evidence; verify persistence after refresh or re-entry when material. Try happy paths, empty states, loading states, invalid inputs, error states, recovery paths, navigation variants, role/permission variants, responsive/mobile variants, persistence/reload points, and reasonable edge cases. Stop at unsafe, paid, destructive, privacy-sensitive, production, or irreversible actions unless the user authorized that exact action and a reset/disposable environment exists. Write each path attempt, trace, result, label, frontend artifact, and source/supporting artifact reference to the ledger immediately after observation.
- Run the Adaptive Exhaustion Gate after each wave: update candidate inventories, manifest, frontier burn-down, and new candidate IDs; retarget from unresolved rows and inventory differences; keep
finality: openwhile safe authorized work remains. Useexhaustedonly when none remains, with exact resume conditions. - For every material user goal, assess path existence and path effort: whether a path exists, where it starts, how many steps and decisions it requires, whether it has detours, repeats, context switches, hidden prerequisites, waiting states, unclear labels, dead ends, or recovery burden. Flag paths that technically work but are unreasonably long, fragile, buried, or cognitively expensive. Write missing-path and overcomplicated-path findings to the ledger.
- Maintain one shared evidence state: candidate inventories, canonical coverage manifest, claim ledger, coverage matrix, path_frontier, evidence debt register, path traces, evidence inventory, clarity lane packets, false positives, rejected claims, blocked checks, avoided checks, missing paths, and untested paths. Every full-frontier material row must use the canonical terminal or nonterminal taxonomy from
references/coverage-manifest.md. - If the available evidence is static only, such as screenshots, README, docs, package scripts, or source snippets with no runnable runtime, route as a static constrained pass. Keep runtime behavior, persistence, accessibility, deployability, and path completion claims provisional, blocked, missing, or evidence debt unless directly proven.
- Pass product path evidence, missing-path candidates, and path-effort notes to
ship-workflow-clarity; ask it for compact lane packets, not a competing full ledger. Clarity/design critique happens after path discovery and initial product evidence, and must tie visual or attention critiques to workflow consequence. - At the end of every wave, read every expected lane output in full, merge normalized lane packets into the ledger, then run an independent verifier against the raw outputs and ledger. The verifier must fail the full-run claim if no browser/computer-use/frontend path-walk occurred while the report claims full Shipworthy. Do not write a wave intelligence summary until the verifier explicitly approves summary-writing.
- Retarget each later wave from verified findings, contradictions, coverage gaps, missing expected paths, overcomplicated paths, path_frontier burn-down, and evidence debt, not from the original lane split.
- Run a fix-cascade check on major recommendations: compare against the no-change baseline, identify what the fix could break downstream, and preserve proof, governance, recovery, accessibility, expert controls, and necessary friction. Write fix-cascade notes to the ledger.
- Run the Raw-Evidence-to-Ledger Reconciliation Gate, then have the final no-overclaim verifier independently regenerate candidate inventories before comparing raw locators/mappings with the manifest. Fail a full-run claim for any unmapped candidate/observation, unresolved nonterminal row, circular census, or final negative pass that lacks source evidence or still finds candidates. Downgrade claims such as ready, works, accessible, robust, secure, deployable, beloved, viral, complete, or full Shipworthy unless directly supported.
- Run the HTML Report Gate for every operational Shipworthy invocation. Generate
readiness-ledger.json,report-input.json, andreadiness-report.htmleven when the run is conditional, static constrained, changed-only, source/CLI-only, or downgraded. Default to~/.shipworthy/runs/<target-slug>/<timestamp>/so the audited repo stays read-only. Use repo-local.shipworthy/reports/<timestamp>/only when the user explicitly requests repo artifacts. - Run the Pre-Final Artifact Assertion: canonical
readiness-ledger.json,report-input.json, andreadiness-report.htmlexist unless artifact writes are blocked; no redundantreadiness-report.jsonis required; final answer includes the absolute HTML path; and if any required item is missing, the final answer leads with missing artifact debt instead of implying completion. - Write the final report only after the final claim ledger, path_frontier burn-down, exhaustion_status, evidence debt, coverage gaps, verified wave summaries, verifier outputs, fix-cascade notes, final drift check, goal_mode_status, multi-agent authorization status, frontend path-walk status, HTML report generation status, mandatory HTML report path, and ledger/evidence paths are complete.
Design Critique Mandate
For every important page, screen, route, panel, dialog, flow, or state, ask:
- Is this ugly, generic, overcluttered, visually noisy, or hard to scan?
- Is attention going to the right thing first?
- Is there one obvious next action where the workflow needs one?
- Is there a reasonable path for what a user would naturally try to do here?
- Is the path too long, buried, repetitive, fragile, or cognitively expensive for the value it provides?
- Is the page saying too much, too early, or in the wrong order?
- Does layout clarify state, progress, object, consequence, and recovery?
- Does the experience feel trustworthy, polished, modern, and worth continuing?
- Would a first-time user feel momentum or friction?
- What should be removed, grouped, renamed, reordered, deemphasized, or made more prominent?
- What would make this simpler, clearer, more effective, and more attention-retaining without hiding proof, controls, recovery, accessibility paths, expert power, or governance boundaries?
Tie every design critique to observed workflow consequence. Do not report taste as severity without user impact.
When the user asks for "beloved", "viral", "attention-retaining", or similar product outcomes, translate that into testable hypotheses: time-to-value, first-run momentum, emotional payoff, repeat-use loop, share/referral moment, trust, perceived quality, and support burden. Do not claim the product will be beloved or viral; report what the evidence suggests would help or block those outcomes.
Reference Routing
Load only the references needed for the current pass:
- Read
references/lane-prompts.mdbefore dispatching product, clarity, design, verifier, or release-gate lanes. - Read
references/browser-evidence-routing.mdbefore native browser, computer-use, or Playwright work. - Read
references/host-execution-recipes.mdbefore invoking target-owned execution. Follow its ordered delegation from existing repository tests, through native adaptive exploration and existing deterministic Playwright replay, to an explicitly authorized target-owned test proposal; otherwise record evidence debt. - Read
references/ledger-validation-contract.mdbefore structured render or import; use itsreferences/schemas/readiness-ledger.schema.json,references/schemas/report-input.schema.json, orreferences/schemas/browser-evidence-envelope.schema.jsonas selected by the declared input type. - Read
references/evidence-import-contract.mdonly for browser, Playwright, or legacy structured input. - Read
references/coverage-manifest.md,references/evidence-state.md, andship-product-workflows/references/path-discovery-and-coverage.mdbefore creating candidate inventories, coverage manifests, ledgers, the material-state control census, coverage matrices, path labels, evidence debt, or readiness claims. - Read
references/final-report-contract.mdbefore writing the final report or roadmap. - Read
references/archetype-overlays.mdwhen the target matches a known product archetype (checkout, auth, ai-chat, dashboard, …). Theprofiles/*.jsonseed path discovery with priors — expected intents, common failure modes, and frequently-missing paths — as hypotheses to confirm or disprove with evidence, never a pass/fail checklist. - Read
references/changed-scope.mdfor a delta / in-session re-audit ("is my change ready?"): scope to the changed surface plus its blast radius, label untouched pathsout_of_scope, and return a verdict scoped to the change — not the whole product. - Read
references/visual-html-report.mdfor every operational Shipworthy invocation. It documents the mandatory HTML dashboard,scripts/render_report.py, and the JSON contract. - Read
references/exports-and-ci.mdwhen the user wants to share, archive, gate, or automate: the mandatory HTML render, the SARIF export (scripts/to_sarif.py), the tamper-evident evidence bundle (scripts/make_bundle.py), the confirmed-only merge gate, the opt-in--interactivereport, and the optional GitHub code-scanning recipe. All local-first; all renders of the finished ledger. - Read
references/pressure-tests.mdwhen validating or forward-testing this skill, or when the user asks whether the orchestration is strong enough.
Output Contract
Lead with findings and readiness truth, organized by action. Use these visible sections before thematic detail: Clear Before Ship for readiness-blocking confirmed failures or missing paths; Fix Next for real non-blocking issues; Not Proven / Not Tested for evidence debt, blocked/avoided/unsafe/unavailable paths, hypotheses, and unverified claims; and Passed / Keep for paths that worked under the tested conditions. Each item must carry one action chip (Fix, Prove, Decide, Skip, or Keep) and one proof chip (Confirmed, Partial, Inferred, or Not tested). Do not use vague visible buckets such as "working signals" or "strong signals" in final user-facing output. Do not claim ready, safe, correct, accessible, persistent, secure, beloved, viral, passing, or fixed without evidence.
For operational Shipworthy runs, include an Orchestration Checkpoint in the report: skill bodies read, references read, target fingerprint, safe-test boundary, ledger location or inline snapshot, goal_mode_status, multi-agent authorization status, frontend path-walk status, actual agent/tool execution mode, runtime driver mode, verifier status, omitted gates, path_frontier burn-down, exhaustion_status, HTML report generation status, mandatory HTML report path, and where raw outputs/evidence live. Under that checkpoint, include a lane roster table with one row per planned lane and columns for lane, scope, required skill/reference, execution status, output/evidence location, and skipped/collapsed/blocking reason. If agent dispatch was skipped because authorization was denied, unavailable, or not received, state "sequential fallback because multi-agent authorization was not granted". If actual frontend path-walking did not occur, state the downgrade reason and do not call the report a full Shipworthy run. If the checkpoint, roster table, path-universe closure, path_frontier closure, verifier certificates, frontend path-walk status, report generation status, or HTML report path is missing, the report is not complete.
For each finding include evidence, user consequence, likely cause, smallest useful fix, counterfactual/no-change baseline when relevant, downstream regression or simplification risk, and exact verification step. For full runs, include the source-backed coverage manifest for every candidate and expected intent, using the canonical frontier statuses and showing owner, variants, evidence, result, and terminal reason.
Canonical artifact gate
Before the verifier approves or HTML is rendered: Re-open both final JSON files from disk, readiness-ledger.json and report-input.json. readiness-ledger.json contains the canonical top-level path_frontier; report-input.json is exactly the current shipworthy/readiness-report-input 1.1 wrapper, and its source_ledger must be structurally identical to readiness-ledger.json. Do not add a second top-level frontier or ad hoc checkpoint to the closed report wrapper. Every Fix finding needs non-empty affected_semantic_keys, a semantic observed_effect_code, and evidence_refs; evidence references are safe relative paths to existing non-empty files under the evidence output, optionally followed by a fragment. Every non-intent frontier row names its correct immediate parent and mechanically derives its semantic key from that parent. Execute both bundled schemas, compare source candidate inventories, frontier identities/counts/qualification/finality, and finding lineage, then render HTML from that exact report input. Missing or divergent canonical data fails completion.
Write the operational checkpoint separately as orchestration-checkpoint.json in the directory containing report-input.json; never inject it into the closed wrapper. Record the human target name, actual lane roster/status/evidence, execution mode, authorization, frontend path-walk, verifier, omissions, ledger/evidence locations, and exhaustion status. scripts/render_report.py is the final fail-closed gate: it checks frontier parents and finding lineage, evidence existence and available-artifact integrity, the computed frontier digest chain, and this checkpoint before writing HTML. Invalid canonical input must not be rendered and must remain unchanged.
For a current full run, path_frontier must be an object, never a list. It must contain rows, discovery_passes, reconciliation_differences, and derived summary alongside its version and closure fields. Every finding's affected_semantic_keys must use exact shipworthy-semantic-v1 keys present in path_frontier.rows, never unversioned aliases or finding-only shorthand. If either artifact uses the legacy list shape, any required object member is absent, or finding lineage does not resolve to exact rows, fail the run before rendering; do not translate, infer, or declare closure from that artifact.
Do not implement fixes unless the user explicitly asks for implementation after the review.
Only when the audit is truly finished and no continuation handoff is required, end an operational Shipworthy final answer that contains Clear Before Ship items with this fix handoff unless the user explicitly forbids follow-up work:
Recommended next step: reply yes and I'll start a persistent fix goal for the Clear Before Ship items using authorized subagents where helpful. I'll apply the fixes safely, verify each one, regenerate the Shipworthy HTML report, and stop only when every remaining item is either passed, intentionally scoped out, or still clearly listed as not proven.
Ledger-derived deliverables (local-first; never a second source of truth). The inline report and self-contained HTML report (scripts/render_report.py; verdict, covered-%, action-first findings, checkpoint) are required for every operational Shipworthy invocation and are generated only after the ledger is final. The HTML report defaults to no JS; --interactive is an opt-in variant that adds client-side filter/search/collapse. Additional exports, when the user wants to share, archive, gate, or automate, are:
- a SARIF 2.1.0 file (
scripts/to_sarif.py) for GitHub code scanning, with an optional merge gate (--gate) that fails on confirmed blockers only; - a tamper-evident evidence bundle (
scripts/make_bundle.py; ledger + report + SARIF + a SHA-256 manifest) for a defensible audit trail — seereferences/exports-and-ci.md. The ledger JSON is itself the canonical machine-readable export.
Common Failure Modes
- Letting
ship-product-workflowsorship-workflow-claritybecome peer controllers with separate final readiness conclusions. - Naming
ship-deep-review,ship-product-workflows, orship-workflow-claritywithout reading their fullSKILL.mdbodies first. - Skipping the lane roster or under-launching agents during a full-blast run when independent agent tooling is available and explicitly authorized.
- Dispatching subagents without explicit user authorization for parallel subagents, delegation, or multi-agent work when platform tool policy requires it.
- Treating Shipworthy instructions as overriding Codex or Claude Code tool policy.
- Pretending
/goalor persistent goal mode was activated when platform goal-mode policy, missing authorization, or missing tooling prevented it. - Sending a full final verdict while a material path_frontier row is still
unattempted,unknown, ormaybe. - Ending an incomplete user-facing response without an exhaustive Remaining Work register and the required continuation/persistent-goal questions as the final text.
- Asking for a fix goal before offering to finish unresolved paths, proof, inventory differences, or omitted gates.
- Stopping because no one asked "do another round" even though the frontier burn-down or verifier still names plausible untested paths.
- Hiding sequential fallback caused by missing multi-agent authorization instead of recording it as orchestration debt.
- Delaying ledger creation until the end, treating the final prose as the ledger, or letting lane agents create competing ledgers.
- Omitting the Orchestration Checkpoint from the final report, leaving agent/sequential fallback, lane roster, or verifier status invisible.
- Omitting
readiness-report.htmlbecause the run was downgraded, static constrained, changed-only, or source/CLI-only. Shipworthy invocation means HTML report, always, unless the user forbids file creation or writes are impossible. - Sending a final answer without first verifying that
readiness-report.htmlexists and linking its absolute path. - Starting with visual judgment before workflow cartography.
- Defaulting to top-task/high-risk sampling when the user invoked this skill for a full readiness run.
- Treating "try every path" as omniscience instead of coverage mapping, actual safe execution, labels, and exclusions.
- Substituting source/CLI/HTTP checks for actual frontend path-walking during a full flagship run.
- Calling a source/CLI/HTTP-only readiness audit a full Shipworthy run.
- Only testing paths that exist and missing reasonable user goals that have no UX path.
- Treating a path as acceptable because it technically completes, while ignoring excessive steps, hidden entry points, repeated decisions, fragile prerequisites, or needless context switches.
- Sending a draft narrative summary to the verifier instead of raw outputs and evidence state.
- Treating agent consensus as evidence.
- Dropping evidence debt between waves.
- Re-deriving prior lane evidence without provenance tags, then counting the same fact twice.
- Making screenshot-only claims about behavior, persistence, accessibility, or reachability.
- Turning clarity critique into generic visual polish.
- Treating "beloved", "viral", or "attention-retaining" as a promise rather than a hypothesis to test.
- Simplifying away proof, governance, recovery, expert controls, accessibility paths, or productive friction.
- Recommending a broad redesign when a smaller fix would solve the observed workflow consequence.
- Skipping the fix-cascade check and proposing changes that create new failure paths.
- Turning product workflow QA into an unbounded backend architecture review.
- Clicking mutating, paid, destructive, publishing, permissioned, privacy-sensitive, production, or irreversible actions without explicit safe-test permission.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

