gilde

← All craftbooks

Upgrade a Dependency

More craftsevalv1.0.2released 2026-09-05

Upgrade dependencies in reviewable stages with proof at every step: a green suite before any bump, smallest-risk-first ordering, call-site adaptations at their real locations, a real suite run between stages, and an honest revert for anything that cannot go green.

Steps

Entry step: survey. Each step names the specialist role it wants; the full working prompt is expandable.

  1. Survey the dependency statedependency auditorentry

    Read the real dependency state and each candidate's locally-readable breaking-change surface, record the green baseline, and stage the work smallest-risk-first.

    Show working prompt
    The upgrade scope: {{scope}}

Establish the REAL dependency state before changing anything. Read `package.json` (and the lockfile if one exists), run `list_packages`, and work out how this project consumes each dependency - registry installs, or a vendored tree the repository documents. Then run the suite with `run_package_script` (`test`) and record that it is green BEFORE any bump. If the suite is already red, record the failure honestly and stop - never upgrade on top of a red suite. If the command needs first-use approval, say so and wait rather than guessing.

For each upgrade candidate, read its breaking-change surface from what is available LOCALLY: changelogs and READMEs inside `node_modules/`, or the repository's own upgrade notes for vendored code. Never invent release notes you did not read - a candidate whose changes you cannot read locally gets staged conservatively and marked unknown. Order the stages smallest-risk-first: patches before minors before majors, one dependency (or one tightly-coupled group) per stage. If nothing is worth upgrading here, record that finding honestly and stop.

Write `{{workPath}}/survey.md` with exactly these sections: `## Current state` (what is installed, from the real manifest and lockfile), `## Candidates` (each candidate with its current and target version and where you read its notes), `## Breaking-change notes` (what actually changes, only from sources you read, each cited with a backtick path), `## Stage plan` (numbered stages, smallest-risk-first, with the reason for the order).

Observable handoff: write the completed result to `{{workPath}}/survey.md` in the project's artifacts drawer with `write_artifact`. Do not merely describe what the file would contain. Re-read it with `read_artifact` before finishing this phase and repair any incomplete sections.
  2. Execute the stagessoftware engineer

    Apply each stage at its real location, adapt the call sites it breaks, and run the suite between stages; revert and record any stage that cannot go green.

    Show working prompt
    Read `{{workPath}}/survey.md` and execute its stage plan one stage at a time. For each stage: apply the version change at its real location - edit the manifest and run `npm_install` for registry dependencies, or replace the vendored tree exactly as the repository's convention documents for vendored ones - then adapt every call site the change breaks at its real location with `read_file` plus `write_file`/`replace_in_file`, and run the suite with `run_package_script` (`test`) before starting the next stage. Never begin a stage while the previous one is red.

A stage that cannot go green gets REVERTED - put the manifest, lockfile, and touched files back exactly as they were - and recorded with the concrete failure, never forced through by weakening tests or pinning over the breakage. A major that turns out to need real design work is deferred honestly, not hacked through. If every stage had to be reverted, record that outcome honestly and stop.

Write `{{workPath}}/change-notes.md` with exactly these sections: `## Stages executed` (each stage with its suite result), `## Files touched` (backtick path per line), `## Adaptations` (each call-site change and why the new version needs it), `## Reverted stages` (each with the concrete failure that forced the revert, or 'none'). Before working, open `{{workPath}}/survey.md` with `read_artifact`.

Observable handoff: write the completed result to `{{workPath}}/change-notes.md` in the project's artifacts drawer with `write_artifact`. Do not merely describe what the file would contain. Re-read it with `read_artifact` before finishing this phase and repair any incomplete sections.
  3. Verify and record the rollbacksoftware engineer

    Re-run the whole suite on the final tree, spot-check the adaptations, and record a concrete rollback path.

    Show working prompt
    Prove the result with fresh eyes. Re-run the whole suite with `run_package_script` (`test`) - it must be green on the final tree; if it is not, go back and fix or revert before verifying again. Re-read `{{workPath}}/change-notes.md` and spot-check each adaptation at its real location with `read_file`. Then record the rollback path: exactly which manifest and lockfile entries (or vendored files) to restore, and in what order, to return to the pre-upgrade state. Anything you could not actually run gets labeled unverified, never claimed.

Write `{{workPath}}/verification.md` with exactly these sections: `## Suite` (the full-suite command and its result), `## Adaptations verified` (which call sites you re-opened and what you confirmed), `## Rollback` (the concrete revert steps), `## Result` (upgraded and green, or what remains unverified and why). Before working, open `{{workPath}}/change-notes.md` with `read_artifact`.

Observable handoff: write the completed result to `{{workPath}}/verification.md` in the project's artifacts drawer with `write_artifact`. Do not merely describe what the file would contain. Re-read it with `read_artifact` before finishing this phase and repair any incomplete sections.
  4. Evaluate the deliverabledependency reviewer

    Independently grade the observable deliverable and route it to finish, repair, or user escalation.

    Show working prompt
    Review `{{workPath}}/verification.md`, `{{workPath}}/survey.md`, `{{workPath}}/change-notes.md` against every criterion below. Inspect the underlying evidence files named by the workflow; do not grade from the author's summary alone.

1. The stages in change-notes.md were real and ordered smallest-risk-first, matching the plan in survey.md or explaining every deviation.
2. Green between stages is receipts, not claims: the suite was genuinely run before the first bump and between stages - judged from the recorded runs, not the author's summary.
3. Breaking-change notes cite sources that were genuinely read locally; nothing is presented as a release note that was invented.
4. Every adaptation cites a real file, and the change at that site matches what the new version actually requires - open the touched files; do not grade from change-notes.md alone.
5. Stages that could not go green were reverted and recorded with concrete reasons; majors that need design work were deferred honestly, not hacked through.
6. verification.md records a concrete, runnable rollback path and the final suite run is green - judged from the recorded run receipts.

Open `{{workPath}}/verification.md`, `{{workPath}}/survey.md`, `{{workPath}}/change-notes.md` with `read_artifact`. Write the evidence-backed review to `{{workPath}}/review.md` in the artifacts drawer with `write_artifact`.

List the findings as a markdown table with columns `| Severity | File | Line | Problem | Fix |` (severities: critical/major/minor/nit; empty table only on PASS). Give each criterion a PASS or FAIL with a concrete path, excerpt, measurement, or observed behavior. End with exactly `Verdict: PASS` or `Verdict: REVISE`. The gate ENFORCES the verdict: a well-formed REVISE is rejected and routed back to `repair` automatically, carrying your findings — so list every finding in the table with a concrete fix. On PASS, `advance_task_step` to `finish`. Never write PASS while a criterion is unmet.
  5. Finishproject lead

    All deterministic and reviewer criteria passed.

    Show working prompt
    The independent review passed. Read `{{workPath}}/review.md` with `read_artifact`, then use `write_task_note` to record a concise DONE summary with the final deliverable paths (`{{workPath}}/verification.md`, `{{workPath}}/survey.md`, `{{workPath}}/change-notes.md`) and the evidence that each acceptance criterion passed. Report DONE without starting new work.
  6. Repair the deliverablesoftware engineer

    Fix only the concrete gaps from the latest independent review.

    Show working prompt
    Read `{{workPath}}/review.md` with `read_artifact` and repair every failed criterion in `{{workPath}}/verification.md`, `{{workPath}}/survey.md`, `{{workPath}}/change-notes.md`. Make changes on each file's declared surface (`write_artifact` for artifact inputs, `write_file` for workspace inputs), not in task notes or a reply. Preserve evidence that already passed. Re-run or re-check anything the reviewer found unproven. Ensure `{{workPath}}/verification.md` is genuinely updated this turn so the repair is observable, then hand it back for independent evaluation.
  7. Escalate unresolved concernsproject lead

    The bounded repair loop ended without a defensible pass.

    Show working prompt
    The deliverable did not pass after 3 review rounds. Do not claim success. Read `{{workPath}}/review.md` with `read_artifact`, then use `write_task_note` to record DONE_WITH_CONCERNS: the unmet criteria, what was attempted, the affected paths, and the smallest user decision or missing input needed to continue.

Triggers

Phrases that suggest this craftbook to a crew.

Source

View this craftbook on GitHub · MIT license