codeassembly-guidance 0.0.0 → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.meta/changelog.json +563 -0
- package/CHANGELOG.md +134 -0
- package/LICENSE +7 -0
- package/README.md +165 -1
- package/content/_partials/README.md +192 -0
- package/content/_partials/code-descriptions.md +4 -0
- package/content/_partials/code-style.md +7 -0
- package/content/_partials/comment-discipline.md +89 -0
- package/content/_partials/concision.md +3 -0
- package/content/_partials/diff-audit-checklist.md +9 -0
- package/content/_partials/file-access.md +4 -0
- package/content/_partials/live-repo-writes.md +13 -0
- package/content/_partials/plain-speech-calibration.md +66 -0
- package/content/_partials/plain-speech.md +13 -0
- package/content/_partials/prose-line-breaks.md +3 -0
- package/content/_partials/record-marker.md +1 -0
- package/content/_partials/reduced-object-relative.md +28 -0
- package/content/_partials/shell-commands.md +3 -0
- package/content/_partials/target-file-set-resolution.md +22 -0
- package/content/_partials/technical-recommendations.md +5 -0
- package/content/_partials/test-structure-audit-checklist.md +7 -0
- package/content/_partials/ticket-assessment-baseline.md +12 -0
- package/content/_partials/ticket-assessment.md +202 -0
- package/content/_partials/work-type-choice.md +13 -0
- package/content/codeassembly-content.yaml +49 -0
- package/content/collections/all.md +11 -0
- package/content/collections/atlassian.md +16 -0
- package/content/collections/recommended.md +34 -0
- package/content/collections/triage.md +77 -0
- package/content/collections/williamthorsen.md +25 -0
- package/content/guidance/README.md +22 -0
- package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
- package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
- package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
- package/content/guidance/rulebooks/accessibility-conventions.md +20 -0
- package/content/guidance/rulebooks/codeassembly-content-specification.md +161 -0
- package/content/guidance/rulebooks/command-output-conventions.md +14 -0
- package/content/guidance/rulebooks/commit-conventions.md +72 -0
- package/content/guidance/rulebooks/generated-content-policy.md +10 -0
- package/content/guidance/rulebooks/live-worktree-policy.md +18 -0
- package/content/guidance/rulebooks/readme-conventions.md +74 -0
- package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
- package/content/guidance/rulebooks/shell-conventions.md +279 -0
- package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
- package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
- package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
- package/content/guidance/shared/AGENTS.md +43 -0
- package/content/scripts/README.md +41 -0
- package/content/scripts/describe-change.mjs +165 -0
- package/content/scripts/get-ticket-id.sh +131 -0
- package/content/scripts/manage-jira-ticket.mjs +209 -0
- package/content/scripts/resolve-frontmatter.sh +540 -0
- package/content/scripts/resolve-review-run.mjs +12 -0
- package/content/scripts/select-lede-exemplars.mjs +208 -0
- package/content/skills/_data/action-items.md +83 -0
- package/content/skills/_data/artifact-conventions.md +969 -0
- package/content/skills/_data/bitbucket-pr-access.md +89 -0
- package/content/skills/_data/branch-format.md +34 -0
- package/content/skills/_data/change-record.md +163 -0
- package/content/skills/_data/complexity-classification.md +58 -0
- package/content/skills/_data/concision.md +23 -0
- package/content/skills/_data/deployed-file-provenance.md +46 -0
- package/content/skills/_data/design-priorities.md +76 -0
- package/content/skills/_data/gh-body-file.md +30 -0
- package/content/skills/_data/git-commands.md +39 -0
- package/content/skills/_data/naming-conventions.md +50 -0
- package/content/skills/_data/pr-resolution.md +25 -0
- package/content/skills/_data/pr-source-resolution.md +36 -0
- package/content/skills/_data/recommendation-gradient.md +90 -0
- package/content/skills/_data/scope-and-deferral.md +83 -0
- package/content/skills/_data/spike-conventions.md +89 -0
- package/content/skills/_data/ticket-evaluation.md +13 -0
- package/content/skills/_data/ticket-id-extraction.md +43 -0
- package/content/skills/_data/ticket-source-resolution.md +147 -0
- package/content/skills/_data/title-templates.md +624 -0
- package/content/skills/_data/title-voice.md +17 -0
- package/content/skills/_data/work-types.json +168 -0
- package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
- package/content/skills/_partials/action-items.md +22 -0
- package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
- package/content/skills/_partials/commit-title-rendering.md +14 -0
- package/content/skills/_partials/gh-body-file.md +22 -0
- package/content/skills/_partials/nested-list-indent.md +9 -0
- package/content/skills/_partials/next-steps-after-plan.md +99 -0
- package/content/skills/_partials/next-steps-after-review.md +350 -0
- package/content/skills/_partials/option-format.md +84 -0
- package/content/skills/_partials/plan-template.md +97 -0
- package/content/skills/_partials/split-launch-prompts.md +5 -0
- package/content/skills/_partials/split-ticket-compose.md +5 -0
- package/content/skills/_partials/split-ticket-create.md +3 -0
- package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
- package/content/skills/_partials/ticket-concision.md +18 -0
- package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
- package/content/skills/_partials/ticket-placement.md +14 -0
- package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
- package/content/skills/_partials/ticket-skeleton.md +13 -0
- package/content/skills/add-change-record/SKILL.md +136 -0
- package/content/skills/add-test-ids/SKILL.md +51 -0
- package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
- package/content/skills/anti-patterns/SKILL.md +57 -0
- package/content/skills/assess-ticket/SKILL.md +46 -0
- package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
- package/content/skills/brainstorming/SKILL.md +107 -0
- package/content/skills/capture-event/SKILL.md +108 -0
- package/content/skills/capture-event/capture-event.mjs +216 -0
- package/content/skills/capture-feedback/SKILL.md +71 -0
- package/content/skills/capture-lede-decision/SKILL.md +163 -0
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
- package/content/skills/classify-complexity/SKILL.md +92 -0
- package/content/skills/collaborate/SKILL.md +86 -0
- package/content/skills/condense-branch/SKILL.md +83 -0
- package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
- package/content/skills/create-commit/SKILL.md +65 -0
- package/content/skills/create-devlog/SKILL.md +108 -0
- package/content/skills/create-gh-pr/SKILL.md +106 -0
- package/content/skills/create-pr/SKILL.md +150 -0
- package/content/skills/create-ticket/SKILL.md +350 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +148 -0
- package/content/skills/design-and-plan/SKILL.md +194 -0
- package/content/skills/development-workflows/SKILL.md +41 -0
- package/content/skills/get-ticket-id/SKILL.md +67 -0
- package/content/skills/groom-backlog/SKILL.md +245 -0
- package/content/skills/groom-backlog/groom-backlog.mjs +106 -0
- package/content/skills/implement-plan/SKILL.md +164 -0
- package/content/skills/index-prototypes/SKILL.md +145 -0
- package/content/skills/index-prototypes/index-prototypes.mjs +328 -0
- package/content/skills/kb-add/SKILL.md +156 -0
- package/content/skills/kb-add/kb-add.mjs +216 -0
- package/content/skills/kb-curate/SKILL.md +117 -0
- package/content/skills/kb-curate/kb-curate.mjs +213 -0
- package/content/skills/kb-edit/SKILL.md +128 -0
- package/content/skills/kb-edit/kb-edit.mjs +219 -0
- package/content/skills/kb-retrieve/SKILL.md +100 -0
- package/content/skills/kb-retrieve/kb-retrieve.mjs +206 -0
- package/content/skills/kb-retrieve-events/SKILL.md +98 -0
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +206 -0
- package/content/skills/kb-update-events/SKILL.md +77 -0
- package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
- package/content/skills/merge-bb-pr/SKILL.md +136 -0
- package/content/skills/merge-gh-pr/SKILL.md +167 -0
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
- package/content/skills/merge-pr/SKILL.md +368 -0
- package/content/skills/migrate-feedback-memories/SKILL.md +136 -0
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
- package/content/skills/people-report/SKILL.md +208 -0
- package/content/skills/plan/SKILL.md +87 -0
- package/content/skills/prepare-prototype-brief/SKILL.md +126 -0
- package/content/skills/pull-from-backlog/SKILL.md +83 -0
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +208 -0
- package/content/skills/refine-plan/SKILL.md +259 -0
- package/content/skills/respond-to-review/SKILL.md +292 -0
- package/content/skills/review-bb-pr/SKILL.md +161 -0
- package/content/skills/review-branch/SKILL.md +301 -0
- package/content/skills/review-criteria/SKILL.md +108 -0
- package/content/skills/review-gh-pr/SKILL.md +155 -0
- package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
- package/content/skills/review-permissions/SKILL.md +39 -0
- package/content/skills/review-pr/SKILL.md +123 -0
- package/content/skills/revise-comments/SKILL.md +115 -0
- package/content/skills/revise-prose/SKILL.md +197 -0
- package/content/skills/revise-prose/revise-prose.mjs +229 -0
- package/content/skills/save-artifact/SKILL.md +69 -0
- package/content/skills/save-plan/SKILL.md +55 -0
- package/content/skills/software-engineering/SKILL.md +74 -0
- package/content/skills/streamline-guidance/SKILL.md +174 -0
- package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
- package/content/skills/summarize-change/SKILL.md +308 -0
- package/content/skills/summarize-chat/SKILL.md +100 -0
- package/content/skills/systematic-debugging/SKILL.md +308 -0
- package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
- package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
- package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
- package/content/skills/systematic-debugging/find-polluter.sh +68 -0
- package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
- package/content/skills/systematic-debugging/test-academic.md +16 -0
- package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
- package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
- package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
- package/content/skills/testing-conventions/SKILL.md +168 -0
- package/content/skills/testing-conventions/mistakes.md +1 -0
- package/content/skills/typescript-testing-conventions/SKILL.md +129 -0
- package/content/skills/update-jira-ticket/SKILL.md +245 -0
- package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
- package/content/skills/update-project-guidance/SKILL.md +300 -0
- package/content/skills/upgrade-dependencies/SKILL.md +139 -0
- package/content/skills/wrap-up/SKILL.md +431 -0
- package/content/subagents/_data/claude.yaml +19 -0
- package/content/subagents/_data/rovo.yaml +31 -0
- package/content/subagents/canary.md +11 -0
- package/content/subagents/entry-drafter.md +187 -0
- package/content/subagents/handoff-reviewer.md +75 -0
- package/content/subagents/plan-reviewer.md +184 -0
- package/content/subagents/plan-reviser.md +88 -0
- package/content/subagents/prose-reviser.md +130 -0
- package/content/subagents/ticket-assessor.md +139 -0
- package/package.json +70 -2
- package/schemas/preferences.v1.json +294 -0
- package/schemas/work-types.v1.json +142 -0
|
@@ -0,0 +1,300 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: update-project-guidance
|
|
3
|
+
description: Generate or refresh the repo-root AGENTS.md for a repository
|
|
4
|
+
user-invocable: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Update project guidance
|
|
8
|
+
|
|
9
|
+
Generate or refresh the repository-root `AGENTS.md`, the repo-specific guidance file that gives AI agents the context that they need to work effectively in the project. It is at the root because that is the project slot loaded by both harnesses: Rovo Dev reads it unaided, and Claude Code loads it through one include.
|
|
10
|
+
|
|
11
|
+
**Announce at start:** "Using update-project-guidance to author or refresh AGENTS.md."
|
|
12
|
+
|
|
13
|
+
## Overview
|
|
14
|
+
|
|
15
|
+
Explore the codebase, classify each finding by scope and tier, and produce a concise `AGENTS.md` that covers everything an agent needs to know about this specific project, and nothing more.
|
|
16
|
+
|
|
17
|
+
**Two paths.** When the repository does not contain any guidance content yet, the **authoring path** drafts a file from the skeleton. When it does, the **refresh path** reconciles against what is already there: It audits the file's claims against the codebase and emits edits, never a replacement. Discovery is shared, and both paths converge on the same closing steps. Phase 1 selects between them.
|
|
18
|
+
|
|
19
|
+
**Core principle:** Every line must merit its inclusion. Omit anything an agent would figure out on its own or that is already covered by general guidance.
|
|
20
|
+
|
|
21
|
+
## Process
|
|
22
|
+
|
|
23
|
+
### Phase 1: Discover
|
|
24
|
+
|
|
25
|
+
Gather project information from these sources (skip any that don't exist).
|
|
26
|
+
|
|
27
|
+
**General baseline:**
|
|
28
|
+
|
|
29
|
+
- `{harness_home_dir}/{harness_guidance_file}` (the harness's own global guidance, not in the repo): Read first; this defines what's already covered and must not be duplicated
|
|
30
|
+
|
|
31
|
+
**Existing guidance (current state):**
|
|
32
|
+
|
|
33
|
+
- `AGENTS.md` (repo root): Read it in full; it is the refresh path's baseline, not background reading
|
|
34
|
+
|
|
35
|
+
**Legacy guidance files (migrate or flag):**
|
|
36
|
+
|
|
37
|
+
- `.agents/PROJECT.md`: The previous location for this file; content should migrate to the repo-root `AGENTS.md`
|
|
38
|
+
- `.agents/AGENTS.md` (in the repo, not the global guidance above): An earlier convention still; content should migrate the same way
|
|
39
|
+
|
|
40
|
+
**Project metadata:**
|
|
41
|
+
|
|
42
|
+
- `package.json` (root): name, workspaces, scripts, engines, type
|
|
43
|
+
- `package.json` (each workspace package): name, description, key dependencies
|
|
44
|
+
- `pnpm-workspace.yaml` / `lerna.json` / similar: Monorepo structure
|
|
45
|
+
|
|
46
|
+
**Configuration:**
|
|
47
|
+
|
|
48
|
+
- `tsconfig.json`: Compiler strictness, module system, paths, target
|
|
49
|
+
- Build configs: Vite, esbuild, webpack, Rollup, etc.
|
|
50
|
+
- Test configs: Vitest, Jest, Playwright, etc.
|
|
51
|
+
- `.editorconfig`, `.prettierrc*`, `eslint.config*`: Formatting and quality rules
|
|
52
|
+
- CI configs: `.github/workflows/`, `.gitlab-ci.yml`, etc.
|
|
53
|
+
|
|
54
|
+
**Documentation:**
|
|
55
|
+
|
|
56
|
+
- `README.md`: Project description, setup instructions
|
|
57
|
+
- `docs/`: Architecture docs, conventions, guides
|
|
58
|
+
|
|
59
|
+
**Discovery should be pragmatic, not exhaustive.** Read root metadata, workspace config, and package-level `package.json` files for names and descriptions. Don't deep-dive into every package's internals. For monorepos, a concise description of each package (name, purpose, key technology) is enough; package-specific details belong at the package level.
|
|
60
|
+
|
|
61
|
+
Collect findings as a flat list before moving to classification.
|
|
62
|
+
|
|
63
|
+
#### Resolve the baseline and select the path
|
|
64
|
+
|
|
65
|
+
The **baseline** is the substantive guidance content that already exists. Choose it by substance, not by existence: Take the repo-root `AGENTS.md` when it states substantive claims, and otherwise fall back to a legacy `.agents/PROJECT.md`, then `.agents/AGENTS.md`, taking the first that does. A stub at the root (a title and a pointer) does not take precedence over a mature legacy file, because a pointer is not a claim.
|
|
66
|
+
|
|
67
|
+
When both legacy files have content, `.agents/PROJECT.md` is the baseline as the later convention, and the other is added to the gap-scan sources so that its content appears in the change list rather than being archived unread.
|
|
68
|
+
|
|
69
|
+
Resolve the baseline in memory. A legacy file is not moved here; its content becomes the baseline and moves to the repo root when Phase 3 writes, which is the only point at which this skill is permitted to write anything.
|
|
70
|
+
|
|
71
|
+
The path follows from what was found. With a baseline, take the **refresh path**. With none (a missing guidance file, or nothing but stubs), take the **authoring path**, because there is nothing to preserve and a bounded gap scan would produce almost nothing.
|
|
72
|
+
|
|
73
|
+
State which path was selected, and why, before proceeding.
|
|
74
|
+
|
|
75
|
+
### Phase 2: Analyze and classify
|
|
76
|
+
|
|
77
|
+
For each finding, assign one of these classes:
|
|
78
|
+
|
|
79
|
+
| Class | Destination | Test |
|
|
80
|
+
| ------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------ |
|
|
81
|
+
| **Ambient** | `AGENTS.md` | Applies only to this repo, and the obvious action goes wrong without it |
|
|
82
|
+
| **Reference** | The owning package's README, or `docs/` | Applies only to this repo, but an agent needs it occasionally |
|
|
83
|
+
| **Already covered** | Omit | Already stated in `{harness_home_dir}/{harness_guidance_file}`, or printed by the tool itself |
|
|
84
|
+
| **General** | Recommend for the global guidance | Applies across repos but not yet in general guidance |
|
|
85
|
+
| **Ambiguous** | Ask the user | Could go either way; collect every such finding into one review at the draft or change-list gate |
|
|
86
|
+
|
|
87
|
+
**Rules:**
|
|
88
|
+
|
|
89
|
+
- Two axes decide the destination. **Scope** (general vs project-specific) separates `{harness_home_dir}/{harness_guidance_file}` from this repo; **tier** (ambient vs reference) then separates what `AGENTS.md` states from what a package README does. Neither axis is nature (prescriptive vs descriptive): Conventions, commands, and architectural decisions all classify the same way whether they are rules or facts.
|
|
90
|
+
- What belongs in a README, and where the rest goes, is stated by {rulebook:readme-conventions}. Consult it before assigning a finding to the reference tier: A README's shape follows from what it describes, so the same finding is placed differently in a library's README and in a monorepo root's.
|
|
91
|
+
- A finding belongs in the ambient tier only when it is absent from the tool's own output _and_ the obvious action goes wrong without it. A command table restates `--help`; a directory listing restates `ls`. Both are reference at best, and reference material injected at launch goes stale silently, because nothing fails when it drifts.
|
|
92
|
+
- Do not duplicate general guidance. If a project-specific convention _extends_ a general one, include only the delta.
|
|
93
|
+
- When unsure about scope, place the finding on the recommended side provisionally and collect every ambiguous finding into one review at the gate below, as multiple-choice questions where possible.
|
|
94
|
+
- When asking option-style questions, follow [option format](#option-format). (Reinforces the rule in `AGENTS.md`: intentional redundancy.)
|
|
95
|
+
- Content that is obvious from reading the code (e.g., "this project uses TypeScript") does not add any value. Include only what would save an agent from a wrong assumption or a slow discovery.
|
|
96
|
+
|
|
97
|
+
<!-- include: ../_partials/action-items.md / -->
|
|
98
|
+
|
|
99
|
+
### Phase 3: Generate
|
|
100
|
+
|
|
101
|
+
Two constraints apply to the repo-root `AGENTS.md`, whichever path produced it:
|
|
102
|
+
|
|
103
|
+
- **No path into a harness-owned directory**, home-anchored or repository-local. One body of text serves every harness (Rovo Dev reads the file directly, Claude Code through an include), so wiring belonging to one of them misleads every other reader. State the fact without the harness path, or record it in that harness's own guidance file.
|
|
104
|
+
- **No `<!-- rulebook:` marker.** `sync` strips a rulebook region from this file: A region introduced by hand disappears on the next run without any warning. Because the sweep matches complete open/close pairs and leaves an unpaired marker in place, the rule covers the marker rather than the region.
|
|
105
|
+
|
|
106
|
+
#### 3a. Ensure prerequisites
|
|
107
|
+
|
|
108
|
+
Before generating the main file, check these prerequisites:
|
|
109
|
+
|
|
110
|
+
**`.agents/preferences.yaml` and `project.slug`:**
|
|
111
|
+
|
|
112
|
+
1. Read `.agents/preferences.yaml`. If it does not exist, or if it exists but does not have a `project.slug` value, ask the user to confirm the project slug (suggest one derived from the repo directory name).
|
|
113
|
+
2. Create or update `.agents/preferences.yaml` to include the confirmed `project.slug`.
|
|
114
|
+
|
|
115
|
+
#### 3b. Authoring path: Produce the draft
|
|
116
|
+
|
|
117
|
+
On the authoring path only. The refresh path skips to 3c.
|
|
118
|
+
|
|
119
|
+
Generate `AGENTS.md` using the standard structure below. Include only sections that have content.
|
|
120
|
+
|
|
121
|
+
```markdown
|
|
122
|
+
# {Project title}
|
|
123
|
+
|
|
124
|
+
## Overview
|
|
125
|
+
|
|
126
|
+
{What the project is, what problem it solves, key technology. 2-4 sentences.}
|
|
127
|
+
|
|
128
|
+
## Project structure
|
|
129
|
+
|
|
130
|
+
{One clause per package: what it owns, plus a pointer to its own README. Never a directory tree; `ls` prints that, and a transcribed one goes stale.}
|
|
131
|
+
|
|
132
|
+
## Commands
|
|
133
|
+
|
|
134
|
+
{Only commands whose absence sends an agent wrong: a required bootstrap, a non-obvious entry point. Omit anything the tool lists from `--help` or a bare invocation.}
|
|
135
|
+
|
|
136
|
+
## Architecture
|
|
137
|
+
|
|
138
|
+
{Only what changes how an agent approaches a change: dependency ordering, and couplings that nothing enforces. Not a recital of the TypeScript, test, or lint configuration.}
|
|
139
|
+
|
|
140
|
+
## Code style
|
|
141
|
+
|
|
142
|
+
{Repo-specific conventions not covered by general guidance. Omit if everything is already general.}
|
|
143
|
+
|
|
144
|
+
## Gotchas
|
|
145
|
+
|
|
146
|
+
{Non-obvious things that trip up agents: Build-order dependencies, tools with surprising behavior, naming inconsistencies, common mistakes.}
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
<HARD-GATE>
|
|
150
|
+
Do NOT write any files until the user has reviewed and approved the draft. Present the draft AGENTS.md content and wait for explicit approval. This applies regardless of perceived simplicity.
|
|
151
|
+
</HARD-GATE>
|
|
152
|
+
|
|
153
|
+
#### 3c. Refresh path: Produce the change list
|
|
154
|
+
|
|
155
|
+
On the refresh path only. The baseline is the working document: Audit what it claims, find what it is missing, and emit edits against it.
|
|
156
|
+
|
|
157
|
+
##### Check the constraints
|
|
158
|
+
|
|
159
|
+
Scan the baseline for a harness-scoped path and for any `<!-- rulebook:` marker. Every hit is a repair, whatever the audit says about it. A harness-scoped path is true for the harness that it names and reads as ambient, so neither audit verdict flags it, and anything the change list does not name passes through untouched.
|
|
160
|
+
|
|
161
|
+
##### Audit the claims
|
|
162
|
+
|
|
163
|
+
Two tiers, because a mature file contains more claims than one exhaustive pass can cover. A 35-line file decomposes into dozens of independently checkable assertions, and one at the line budget into several hundred.
|
|
164
|
+
|
|
165
|
+
- **Tier 1: Every checkable token, exhaustively.** Paths, filenames, command strings, counts, package and symbol names. Drift appears in these tokens: a directory listing that has gained an entry, a count off by two, a tool named one hop from what runs.
|
|
166
|
+
- **Tier 2: Narrative claims, in the sections touched by the gap-scan window.** Unquantified prose is audited where the repo has moved under it, not everywhere.
|
|
167
|
+
|
|
168
|
+
Check the claim, not the section. A stale listing looks entirely plausible and is wrong only once the directory is listed, so recognizing a section's shape is the signal to slow down rather than to move on.
|
|
169
|
+
|
|
170
|
+
Record every audited claim as a ledger row (claim, verdict, evidence):
|
|
171
|
+
|
|
172
|
+
- `holds`: Confirmed. **Requires an evidence token**: the command run, or the `path:line` read.
|
|
173
|
+
- `drifted`: No longer true, stating what is true now.
|
|
174
|
+
- `unchecked`: Not verified, stating why.
|
|
175
|
+
|
|
176
|
+
A `holds` row without an evidence token is not a permitted state. The audit is otherwise unfalsifiable: A claim that holds does not produce an edit, so a run that checked nothing emits the same change list as one that checked everything.
|
|
177
|
+
|
|
178
|
+
Close the ledger by naming what was not audited, so that a bounded run reads as bounded.
|
|
179
|
+
|
|
180
|
+
Re-run the Phase 2 classification only on the sections touched by the window, plus one pass against `{harness_home_dir}/{harness_guidance_file}` for content that the global file now states. What was ambient last month is still ambient unless something moved.
|
|
181
|
+
|
|
182
|
+
##### Scan for gaps
|
|
183
|
+
|
|
184
|
+
Bounded, because an unbounded "what else should this file say?" is effectively a redraft.
|
|
185
|
+
|
|
186
|
+
**The window extends back to whichever is earlier**: the last commit touching `AGENTS.md`, or twenty commits. Twenty is a floor, never a ceiling: A drive-by edit that touched the file two commits ago leaves the window at twenty, not at two. Add `git status --porcelain`, since the common case is an author invoking this mid-session with uncommitted work.
|
|
187
|
+
|
|
188
|
+
Every `git log` here names its own `--format`. A global or repository `format.pretty` rewrites the output, and a naive parse then reads mangled text without any sign that anything went wrong.
|
|
189
|
+
|
|
190
|
+
When git cannot answer (outside a repository, or the file untracked), state the bound at the gate as "whole repo, additions only" rather than leaving it unstated.
|
|
191
|
+
|
|
192
|
+
Then one unbounded check against the skeleton: Is an ambient category missing altogether, such as a required bootstrap, a dependency ordering, or a tool that behaves surprisingly? It is the only check for a fact that was always worth stating and never captured.
|
|
193
|
+
|
|
194
|
+
##### Emit the change list
|
|
195
|
+
|
|
196
|
+
Four kinds of edit, and nothing else:
|
|
197
|
+
|
|
198
|
+
| Kind | Use |
|
|
199
|
+
| ------------ | ----------------------------------------------- |
|
|
200
|
+
| **repair** | A claim that drifted, or a constraint violation |
|
|
201
|
+
| **remove** | An assertion that lost the ambient tier |
|
|
202
|
+
| **relocate** | A section moved behind a pointer |
|
|
203
|
+
| **add** | Something the gap scan found |
|
|
204
|
+
|
|
205
|
+
Anything not named passes through byte-identical.
|
|
206
|
+
|
|
207
|
+
**A repair quotes verbatim.** It is an old-text/new-text pair whose old text is copied from the baseline. Do not render `AGENTS.md` content in any other form: not as a rewritten section, and not as "here is how that section should read". An edit that cannot quote what it replaces is not a repair, and this rule exists to catch a rewritten section presented as one large repair.
|
|
208
|
+
|
|
209
|
+
Placement:
|
|
210
|
+
|
|
211
|
+
- An **addition** goes in its matching skeleton section. A new section needs the user's agreement.
|
|
212
|
+
- A **removal** or **relocation** names its destination as a recommendation. Writing to a package README touches a separate file and needs its own approval.
|
|
213
|
+
- **Relocate when the file exceeds its budget.** Additions can push it past the line budget, and surviving prose may not be reworded to make room, so moving a section behind a pointer is the sanctioned response.
|
|
214
|
+
|
|
215
|
+
##### Worked example
|
|
216
|
+
|
|
217
|
+
```
|
|
218
|
+
Ledger
|
|
219
|
+
|
|
220
|
+
| Claim | Verdict | Evidence |
|
|
221
|
+
| ------------------------------------------ | --------- | ------------------------------------------------ |
|
|
222
|
+
| `.config/` holds `vitest/` and `eslint/` | drifted | `ls .config/`: also holds `readyup.config.ts` |
|
|
223
|
+
| `packages/` holds five packages | holds | `ls packages/` → 5 entries |
|
|
224
|
+
| `pnpm run bootstrap` builds every package | holds | `package.json:14` |
|
|
225
|
+
| The compile cache is keyed on inputs alone | unchecked | upstream behavior, not verifiable from this repo |
|
|
226
|
+
|
|
227
|
+
Not audited: the Code style section, which the window did not touch.
|
|
228
|
+
|
|
229
|
+
Change list
|
|
230
|
+
|
|
231
|
+
1. repair: the `.config/` listing
|
|
232
|
+
old: Configuration lives in `.config/vitest/` and `.config/eslint/`.
|
|
233
|
+
new: Configuration lives in `.config/`, holding `vitest/`, `eslint/`, and `readyup.config.ts`.
|
|
234
|
+
2. relocate: Commands moves to `packages/agents/README.md` behind a pointer; the addition below puts the file two lines over budget.
|
|
235
|
+
3. add to Gotchas: `rdy compile` regenerates `kits/default.js`, so an edit to the `.js` is lost on the next build.
|
|
236
|
+
```
|
|
237
|
+
|
|
238
|
+
<HARD-GATE>
|
|
239
|
+
Do NOT write any files until the user has reviewed and approved both the ledger and the change list. This applies regardless of perceived simplicity.
|
|
240
|
+
</HARD-GATE>
|
|
241
|
+
|
|
242
|
+
#### 3d. Write files
|
|
243
|
+
|
|
244
|
+
After the user approves:
|
|
245
|
+
|
|
246
|
+
1. Write `AGENTS.md` at the repository root. Rovo Dev loads it from there without further wiring. On the refresh path the content is the baseline with the approved edits applied: Apply them rather than re-rendering the file, so that everything the change list does not name survives unaltered. A baseline that came from a legacy path is written here too.
|
|
247
|
+
2. Ensure `.claude/CLAUDE.md` points to it through a raw include. Claude Code resolves a relative include against the directory of the file that contains it, not against the repository root, so an include written in `.claude/CLAUDE.md` must point up out of `.claude/` to the root: `@../AGENTS.md`. Derive the include from where the importing file is rather than copying a literal, and confirm that the path to which it resolves is the guidance file that you just wrote.
|
|
248
|
+
- If `.claude/CLAUDE.md` does not exist, create it with that include as its content.
|
|
249
|
+
- If it exists and contains a prose instruction referencing the guidance file (e.g., `Read @../AGENTS.md, which provides...`), replace it with the raw include.
|
|
250
|
+
- If it exists with an include that resolves anywhere else (a stale `@.agents/PROJECT.md`, or any path that does not point up out of `.claude/`), repoint it.
|
|
251
|
+
- If it exists with other content that does not point to any guidance file, add the include on its own line.
|
|
252
|
+
- If it exists with content that has special instructions beyond a simple include, present a recommendation to the user and wait for their decision before modifying.
|
|
253
|
+
|
|
254
|
+
#### 3e. Handle legacy files
|
|
255
|
+
|
|
256
|
+
If legacy guidance files were found in Phase 1 (`.agents/PROJECT.md` or `.agents/AGENTS.md`):
|
|
257
|
+
|
|
258
|
+
1. Confirm with the user that the project-specific content has been migrated to the repo-root `AGENTS.md`.
|
|
259
|
+
2. Preserve any include that the legacy file resolved for itself. When `.agents/PROJECT.md` included a sibling by a bare relative path, that include resolves to a different file from the repository root, so every such include needs its own path re-derived against the new location.
|
|
260
|
+
3. Recommend removing or archiving the legacy files. Do not delete without explicit approval.
|
|
261
|
+
|
|
262
|
+
#### 3f. Handle general-guidance recommendations
|
|
263
|
+
|
|
264
|
+
If any findings were classified as **general** (cross-repo) in Phase 2:
|
|
265
|
+
|
|
266
|
+
1. Present them as a bulleted list after the main file is written.
|
|
267
|
+
2. Name where each one belongs, deciding by whether the harness's guidance file is generated. A file containing a `codeassembly` marker is rendered on every install, so an edit to it is discarded or freezes the file against later updates; the content belongs in a rulebook with `delivery: ambient` in a source declared by the user's `codeassembly.yaml`, and `sync --global` renders that rulebook into the file. A file without a marker is the user's own. See [deployed-file provenance](../_data/deployed-file-provenance.md) for the detection rule and the routes that it implies.
|
|
268
|
+
3. When the file is the user's own, offer to integrate the recommendations: On approval, read it, place each one in the section that fits, and propose a name before adding a new section. Never append blindly, and never write into a generated file.
|
|
269
|
+
|
|
270
|
+
#### 3g. Run the guidance checklist
|
|
271
|
+
|
|
272
|
+
Close by running the published `guidance` checklist against the result: `rdy run --packages`, from the repository root.
|
|
273
|
+
|
|
274
|
+
Skip the step when `rdy` is unavailable, or when the checklist is not published by any configured package. It is a development dependency of the package that publishes it, not something a consuming repository inherits. Report the step as skipped; never report a pass that it did not produce.
|
|
275
|
+
|
|
276
|
+
The freshness check reads committed history, so the write just made does not change its result. On the stale file that motivated a refresh it still reports stale, and its remediation text advises running this very skill. That is expected, and it clears when the change is committed: Do not act on that advice, and do not commit in order to clear it.
|
|
277
|
+
|
|
278
|
+
## Quality checklist
|
|
279
|
+
|
|
280
|
+
Before presenting the draft or the change list, verify:
|
|
281
|
+
|
|
282
|
+
- [ ] The file does not contain a path into a harness-owned directory, home-anchored or repository-local
|
|
283
|
+
- [ ] The file does not contain a `<!-- rulebook:` marker anywhere
|
|
284
|
+
- [ ] The file is at most 200 lines, matching the ambient budget against which the published guidance checklist reports; anything that pushed it over was moved to the package level behind a pointer
|
|
285
|
+
- [ ] The file does not duplicate any content from `{harness_home_dir}/{harness_guidance_file}`
|
|
286
|
+
- [ ] The file does not contain a section that merely restates what's obvious from the code
|
|
287
|
+
- [ ] Commands listed are ones that an agent would actually need (not exhaustive npm script listings)
|
|
288
|
+
- [ ] Each command group states where to run it (repo root, package directory, etc.); don't assume the agent knows
|
|
289
|
+
- [ ] Architecture section focuses on decisions that affect how to make changes, not documentation for its own sake
|
|
290
|
+
- [ ] Gotchas are genuinely non-obvious, not things that an agent would discover from a type error or linter warning
|
|
291
|
+
|
|
292
|
+
## Key principles
|
|
293
|
+
|
|
294
|
+
- **Conciseness over completeness**: A shorter file that covers the essentials is better than a comprehensive one that wastes context window
|
|
295
|
+
- **Scope-aware**: Read general guidance first, never duplicate it
|
|
296
|
+
- **Interactive**: Ask when classification is unclear, in one batch at the gate rather than one question per turn
|
|
297
|
+
- **Portable**: This skill works in any repo that follows the repo-root `AGENTS.md` convention
|
|
298
|
+
- **Honest about uncertainty**: If something might belong in general guidance, say so rather than silently including it
|
|
299
|
+
|
|
300
|
+
<!-- include: ../_partials/option-format.md / -->
|
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: upgrade-dependencies
|
|
3
|
+
description: Use when upgrading, updating, or bumping dependencies in any project managed by package.json. Covers routine patch/minor updates, major version migrations, security vulnerability remediation, and peer dependency conflict resolution.
|
|
4
|
+
user-invocable: true
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
# Upgrade dependencies
|
|
8
|
+
|
|
9
|
+
Structured process for autonomously upgrading dependencies in a project managed by `package.json`.
|
|
10
|
+
|
|
11
|
+
**Core principle:** Assess before acting. Understand the full scope, triage by risk, execute incrementally, and do not trust a green signal that you have not verified end to end.
|
|
12
|
+
|
|
13
|
+
The skill is package-manager-agnostic. Commands are named by role ("the PM's outdated report"), with one concrete form shown as an example when that helps; the example illustrates the role, it never defines it. Ecosystem facts (which endpoint works, which plugin is compatible) go stale; when a mechanic is PM-specific or time-sensitive, resolve it at execution time from the channels in [Resolving specifics](#resolving-specifics).
|
|
14
|
+
|
|
15
|
+
## Workflow
|
|
16
|
+
|
|
17
|
+
### 1. Detect
|
|
18
|
+
|
|
19
|
+
Identify the environment before assessing:
|
|
20
|
+
|
|
21
|
+
- **Package manager**, from the lockfile: `pnpm-lock.yaml` → pnpm, `package-lock.json` → npm, `yarn.lock` → yarn, `bun.lock`/`bun.lockb` → bun. Use that PM's commands for every query, install, and audit below.
|
|
22
|
+
- **Workspace layout**: Single package or monorepo (workspace globs in `package.json`, `pnpm-workspace.yaml`, or the PM's equivalent). In a monorepo, every step fans out across all workspaces, never the root alone.
|
|
23
|
+
- **Support policy**, the project's own commitments: Node floor (`engines`, `.nvmrc`, CI matrix), published peer ranges, runtime targets. These bound every upgrade; changing one is a consumer-facing decision, not a side effect.
|
|
24
|
+
- **Project scripts**: Read `package.json` for the actual build/test/lint script names. Never assume generic names.
|
|
25
|
+
- **Update tooling**: Note any update-automation config (ncu/`.ncurc`, renovate, dependabot). Any pin made later must be mirrored there.
|
|
26
|
+
|
|
27
|
+
### 2. Assess
|
|
28
|
+
|
|
29
|
+
Before touching anything:
|
|
30
|
+
|
|
31
|
+
- **Check for in-progress upgrades.** Look for uncommitted manifest or lockfile changes in the working tree before reading the outdated report, which reflects that state: An upgrade already applied there is absent from the report. Verify such changes through the quality gate before planning new upgrades.
|
|
32
|
+
- **Read the full outdated report.** Run the PM's recursive outdated report (e.g. `pnpm outdated --recursive`) and read every row. Never truncate, page, or sample it; a hidden row is an upgrade that resurfaces as a surprise at final verification.
|
|
33
|
+
- **Check vulnerabilities, and verify the check ran.** Run the PM's audit command and confirm it actually returned results. Audit endpoints are sometimes retired while PMs still call them (pnpm's audit endpoint, for one), so a failing audit channel is a lookup problem, not a reason to skip: Fall back to the project's own audit tooling, the registry's advisory API, or an independent vulnerability scanner. Prioritize whatever the working channel reports.
|
|
34
|
+
- **Inspect ceilings before installing.** For each planned upgrade, read the registry metadata first: `<pm> view <pkg> peerDependencies engines peerDependenciesMeta`. A ceiling is anything that caps a package below latest: a transitive peer pin on a foundation package, an `engines.node` requirement above the project's floor, or the project's own support policy. Finding ceilings now shapes the plan; finding them mid-install produces thrash.
|
|
35
|
+
- **Check whether a "required" peer is optional.** Before adding a peer that the upgrade appears to demand, read `peerDependenciesMeta`: An optional peer is satisfied transitively, does not produce an unmet-peer warning, and does not need a manifest entry in a project that does not use it directly.
|
|
36
|
+
- **Recall prior learnings.** If a knowledge store is registered, invoke `{skill:kb-retrieve-events}` for events touching the packages and tools in scope; past upgrades often recorded the exact ceiling, shim, or retired endpoint that you are about to rediscover. Skip this step when a knowledge store is not configured.
|
|
37
|
+
|
|
38
|
+
### 3. Triage
|
|
39
|
+
|
|
40
|
+
| Category | Risk | Action |
|
|
41
|
+
| ---------------------------- | ------ | ------------------------------------------------ |
|
|
42
|
+
| **Security** (advisory hits) | Urgent | Fast-track the actionable ones in a dedicated PR |
|
|
43
|
+
| **Patch** (x.y.Z) | Low | Batch together |
|
|
44
|
+
| **Minor** (x.Y.0) | Medium | Check changelog first, then batch with patches |
|
|
45
|
+
| **Major** (X.0.0) | High | Individual evaluation: Research before upgrading |
|
|
46
|
+
|
|
47
|
+
Check changelogs for ALL updates, not just majors. Minor bumps can contain behavioral changes.
|
|
48
|
+
|
|
49
|
+
Four triage judgments go beyond the version-number table:
|
|
50
|
+
|
|
51
|
+
- **Not every advisory is actionable.** For a transitive advisory, check whether re-resolving it within its parent's range, or upgrading the direct dependency that pulls it in, resolves it. When a fix does not exist upstream, record the advisory as a known issue in the PR body rather than force a version with an override.
|
|
52
|
+
- **Ceilings are policy, not just conflicts.** The target for each package is the highest version compatible with the project's support policy, not merely the highest that installs without a dependency-vs-dependency conflict. A pin can be forced by the Node floor, by a transitive peer cap, or by a single package's `engines`; each is a deliberate ceiling, and a ceiling that would move the project's own support policy (e.g. raising the Node floor) is a consumer-facing breaking change to decide, not a technicality to absorb. The `@types/node` major tracks the Node major, so its target is the major of the Node floor, whatever the outdated report lists as latest.
|
|
53
|
+
- **Identify cohorts.** Interdependent majors whose peer constraints reference each other (a linter major and its plugin majors, a framework and its adapter) cannot be upgraded separately: Any split leaves an uninstallable intermediate state. Treat such a cohort as a single unit through planning, execution, and commit.
|
|
54
|
+
- **Watch for abandoned-at-latest packages.** The outdated report cannot reveal a package that is simultaneously "latest" and broken under the new major of its host (it calls an API removed by the host). Only running the target major reveals these: After any major runtime, framework, or linter bump, run the tool and watch for removed-API errors, and expect the remedy to be migrating to a maintained fork rather than any version bump.
|
|
55
|
+
|
|
56
|
+
### 4. Plan
|
|
57
|
+
|
|
58
|
+
**Scope:**
|
|
59
|
+
|
|
60
|
+
- Actionable security fixes: Always a dedicated fast-track PR.
|
|
61
|
+
- Patches/minors: Batch in one PR.
|
|
62
|
+
- Majors: If 2 or fewer, include in the same PR as sequential commits; if more, separate PR per major.
|
|
63
|
+
|
|
64
|
+
**Execution order**: Follow the dependency graph, foundations first:
|
|
65
|
+
|
|
66
|
+
1. Language/runtime types (`typescript`, `@types/node`)
|
|
67
|
+
2. Frameworks (`react`, `next`, `vue`)
|
|
68
|
+
3. Framework dependents (`react-router`, `@mui/material`)
|
|
69
|
+
4. Tooling (`eslint`, `prettier`, `vitest`)
|
|
70
|
+
5. Leaf dependencies
|
|
71
|
+
|
|
72
|
+
**Commit granularity:** One major per commit for bisectability, except a cohort, which forms one atomic commit because any smaller step is uninstallable.
|
|
73
|
+
|
|
74
|
+
**Plan every pin twice.** A package held below latest has two obligations: a recorded rationale (in the commit body or ticket, so that a future maintainer can tell a deliberate ceiling from an oversight) and a matching cap in the update tooling (ncu filter, renovate/dependabot ignore rule) so that the next automated bump does not silently revert it.
|
|
75
|
+
|
|
76
|
+
### 5. Execute
|
|
77
|
+
|
|
78
|
+
For each dependency or batch, install with the PM's add command at an explicit version (e.g. `pnpm add -D <pkg>@<version>`; use the PM's workspace flags to target the right workspace), then verify with the project's own quality-gate scripts before moving on.
|
|
79
|
+
|
|
80
|
+
**Major-upgrade pre-flight, before installing:**
|
|
81
|
+
|
|
82
|
+
1. Read the migration guide and changelog.
|
|
83
|
+
2. Check for official codemods and run them before making manual changes.
|
|
84
|
+
3. Verify that downstream packages support the new major (registry metadata, changelogs), including shared configs and the plugins that they pull in transitively: Read each one's peer range and changelog. When one of them does not support the new major and a maintained fork does not exist, hold the upgrade at its ceiling.
|
|
85
|
+
|
|
86
|
+
**Peer dependency conflicts** come in two kinds; distinguish them before acting:
|
|
87
|
+
|
|
88
|
+
- **Genuine incompatibility:** The package really does not support the new version. Resolve the actual conflict: Upgrade the conflicting packages to compatible versions, or hold the upgrade at the ceiling. Never mask it with dependency overrides, legacy-peer-deps behavior, or disabling strict peer checks.
|
|
89
|
+
- **Ecosystem lag:** The declared peer range excludes the new major, but the package works because it shims the removed APIs internally. Verify which kind you have by inspecting the package's use of the removed API (does its code path call the removed method, or route through a compat layer?). Clear a confirmed false positive through the PM's sanctioned allowance mechanism (pnpm's is `pnpm.peerDependencyRules.allowedVersions`; find the current PM's equivalent in its docs), scoped to the specific package and range, never via blanket suppression.
|
|
90
|
+
|
|
91
|
+
**Fork and successor swaps preserve the public surface.** When an abandoned package is replaced by a maintained fork, the swap can rename what consumers reference (rule namespaces, export names). Keep the old surface working (remap old names to new via the project's config or an adapter) so that downstream consumers' overrides and references survive the swap.
|
|
92
|
+
|
|
93
|
+
**Curate new recommended rules per rule.** A linter or plugin major typically expands its recommended set, flagging existing code. Decide adopt (fix the code) versus disable (in config, with a note) for each new rule against the project's philosophy. Neither blanket adoption nor blanket suppression is a decision.
|
|
94
|
+
|
|
95
|
+
### 6. Verify
|
|
96
|
+
|
|
97
|
+
A green signal is only as good as what it exercised. Each check below exists because a check can pass without exercising what it appears to verify:
|
|
98
|
+
|
|
99
|
+
- **Force a clean, non-cached run** of the full quality gate (build + type-check + test + lint). An incremental "no changes, skipping" pass proves nothing about the new versions. Confirm every referenced lint rule id resolves: Flat-config linters throw on unknown rule ids even for rules set to `off`.
|
|
100
|
+
- **Rebuild before self-hosted checks.** When a repo checks itself with its own compiled output (a config package linting itself with its own config), rebuild first or the check runs against stale output.
|
|
101
|
+
- **Smoke-test opt-in surfaces.** A self-linting config package exercises only its default config path; instantiate each optionally-loaded config under the new major, since the configs not used by the host repo are the ones most at risk.
|
|
102
|
+
- **Re-run the outdated report and enumerate the pins.** The end state is exactly N intentional pins, each with its recorded rationale and its matching update-tooling cap. Anything below latest without both is unfinished work, not an acceptable remainder.
|
|
103
|
+
- **Re-run the vulnerability check** through the channel verified in Assess. The end state is every advisory either resolved or recorded as a known issue.
|
|
104
|
+
- **Check root↔workspace alignment** in a monorepo: A root-only bump leaves workspaces on the old version; confirm the same dependency resolves to aligned versions across workspaces.
|
|
105
|
+
- **Assess consumer impact for published packages.** If an upgrade raised the package's effective engine or peer requirements, that narrowing is a breaking change for consumers: Plan a major release with matching `peerDependencies` updates, marked per the project's breaking-change convention.
|
|
106
|
+
|
|
107
|
+
### 7. Commit and capture
|
|
108
|
+
|
|
109
|
+
One commit per logical change (a cohort is one logical change, and so is a major together with the code and config adaptations that it requires), each leaving the repo green. Compose each message per `{rulebook:commit-conventions}` with the `deps` work type, and put each pin's rationale in the body of the commit that introduces it.
|
|
110
|
+
|
|
111
|
+
If a knowledge store is registered, invoke `{skill:capture-event}` for each ecosystem fact discovered the hard way (a retired endpoint, a shim that clears an unmet-peer false positive, a fork swap, a ceiling and its reason) so that the next upgrade recalls it instead of rediscovering it. Skip when a knowledge store is not configured.
|
|
112
|
+
|
|
113
|
+
## Resolving specifics
|
|
114
|
+
|
|
115
|
+
Ecosystem facts go stale; these channels do not. When guidance in this skill disagrees with what a channel reports, trust the channel.
|
|
116
|
+
|
|
117
|
+
- **Registry metadata**, `<pm> view <pkg> peerDependencies engines peerDependenciesMeta versions`: The authoritative source for ceilings, peer ranges, and optionality.
|
|
118
|
+
- **Changelogs, release notes, and migration guides**: Fetch via available web tools; the package's repository and documentation site are the sources for behavioral changes and codemods.
|
|
119
|
+
- **The package manager's documentation**: The sanctioned mechanism for peer allowances, workspace fan-out flags, and audit alternatives is PM-specific and changes across PM majors; look it up rather than assuming.
|
|
120
|
+
- **Official codemods**: Check the framework or tool's migration guide for a codemod before planning manual edits.
|
|
121
|
+
- **The knowledge store**: Prior upgrade events, when a store is registered.
|
|
122
|
+
|
|
123
|
+
## Common mistakes
|
|
124
|
+
|
|
125
|
+
| Mistake | Fix |
|
|
126
|
+
| --------------------------------------------- | ---------------------------------------------------------------------- |
|
|
127
|
+
| Skip the vulnerability check when audit fails | A dead audit channel is a lookup problem; fall back, never skip |
|
|
128
|
+
| Truncate the outdated report | Read every row; hidden rows resurface at final verification |
|
|
129
|
+
| Skip changelogs for minors | Minor bumps can contain behavioral changes |
|
|
130
|
+
| Batch unrelated majors in one commit | One major per commit for bisectability |
|
|
131
|
+
| Split a cohort to honor one-major-per-commit | A cohort is one atomic commit; any split is uninstallable |
|
|
132
|
+
| Run the PM's blanket latest-update command | Ignores semver ranges and pulls unplanned majors |
|
|
133
|
+
| Use interactive flags | Requires human input; breaks autonomous operation |
|
|
134
|
+
| Suppress peer warnings with overrides | Verify shim-vs-break, then use the PM's sanctioned allowance mechanism |
|
|
135
|
+
| Pin without capping the update tooling | The next automated bump silently reverts an uncapped pin |
|
|
136
|
+
| Take the latest `@types/node` major | Match its major to the project's Node floor |
|
|
137
|
+
| Trust a cached green run | Force a clean run; confirm the gate exercised the new versions |
|
|
138
|
+
| Blanket-adopt or blanket-suppress new rules | Decide adopt vs disable per rule against the project's philosophy |
|
|
139
|
+
| Assume generic script names (`pnpm build`) | Read `package.json` for the project's actual script names |
|