codeassembly-guidance 0.5.0 → 0.6.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.
Files changed (71) hide show
  1. package/.meta/changelog.json +306 -0
  2. package/CHANGELOG.md +73 -0
  3. package/README.md +55 -4
  4. package/content/_partials/finding-grades.md +4 -0
  5. package/content/codeassembly-content.yaml +2 -0
  6. package/content/collections/recommended.md +5 -2
  7. package/content/guidance/_harnesses/rovo/AGENTS.md +0 -1
  8. package/content/guidance/rulebooks/accessibility-conventions.md +26 -6
  9. package/content/guidance/rulebooks/cli-conventions.md +17 -2
  10. package/content/guidance/rulebooks/codeassembly-content-specification.md +11 -11
  11. package/content/guidance/rulebooks/machine-readable-output-conventions.md +85 -0
  12. package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
  13. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +10 -10
  14. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +7 -3
  15. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +3 -1
  16. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -5
  17. package/content/scripts/check-prose.mjs +1 -1
  18. package/content/scripts/describe-change.mjs +68 -68
  19. package/content/skills/_data/action-items.md +2 -2
  20. package/content/skills/_data/artifact-conventions.md +20 -10
  21. package/content/skills/_data/concision.md +1 -1
  22. package/content/skills/_data/entry-points.md +37 -0
  23. package/content/skills/_data/recommendation-gradient.md +6 -6
  24. package/content/skills/_data/spike-conventions.md +13 -3
  25. package/content/skills/_data/ticket-source-resolution.md +21 -4
  26. package/content/skills/_data/title-templates.md +4 -4
  27. package/content/skills/_partials/commit-title-rendering.md +2 -1
  28. package/content/skills/_partials/next-steps-after-plan.md +4 -3
  29. package/content/skills/_partials/option-format.md +8 -8
  30. package/content/skills/_partials/plan-template.md +3 -1
  31. package/content/skills/_partials/resolve-plan-and-ticket.md +22 -0
  32. package/content/skills/_partials/split-launch-prompts.md +1 -1
  33. package/content/skills/_partials/ticket-criteria-conventions.md +2 -0
  34. package/content/skills/analyze-performance/SKILL.md +102 -0
  35. package/content/skills/analyze-performance/analyze-performance.mjs +70 -0
  36. package/content/skills/assess-code-health/SKILL.md +16 -14
  37. package/content/skills/assess-code-health/assess-code-health.mjs +29 -28
  38. package/content/skills/assess-usability/SKILL.md +5 -3
  39. package/content/skills/convert-agent-prompt/SKILL.md +60 -0
  40. package/content/skills/create-commit/SKILL.md +10 -5
  41. package/content/skills/create-pr/SKILL.md +11 -11
  42. package/content/skills/create-ticket/SKILL.md +1 -0
  43. package/content/skills/design-and-plan/SKILL.md +2 -2
  44. package/content/skills/implement-plan/SKILL.md +1 -28
  45. package/content/skills/index-prototypes/SKILL.md +36 -17
  46. package/content/skills/index-prototypes/index-prototypes.mjs +14 -14
  47. package/content/skills/investigate-spike/SKILL.md +48 -0
  48. package/content/skills/prepare-prototype-brief/SKILL.md +17 -13
  49. package/content/skills/refine-plan/SKILL.md +7 -4
  50. package/content/skills/refine-prototype/SKILL.md +5 -5
  51. package/content/skills/review-branch/SKILL.md +7 -7
  52. package/content/skills/review-criteria/SKILL.md +3 -3
  53. package/content/skills/review-gh-pr/SKILL.md +1 -1
  54. package/content/skills/revise-prose/SKILL.md +9 -8
  55. package/content/skills/revise-prose/revise-prose.mjs +2 -2
  56. package/content/skills/start-ticket/SKILL.md +27 -0
  57. package/content/skills/summarize-change/SKILL.md +17 -9
  58. package/content/skills/testing-conventions/SKILL.md +12 -1
  59. package/content/skills/triage-spike-findings/SKILL.md +31 -12
  60. package/content/skills/typescript-testing-conventions/SKILL.md +40 -0
  61. package/content/subagents/_data/claude.yaml +3 -0
  62. package/content/subagents/code-health-assessor.md +4 -4
  63. package/content/subagents/disposition-challenger.md +3 -4
  64. package/content/subagents/entry-drafter.md +2 -2
  65. package/content/subagents/handoff-reviewer.md +1 -1
  66. package/content/subagents/prototype-builder.md +69 -0
  67. package/content/subagents/usability-assessor.md +1 -1
  68. package/package.json +5 -4
  69. package/schemas/preferences.v1.json +1 -1
  70. package/schemas/work-types.v1.json +1 -1
  71. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +0 -4
@@ -1,5 +1,5 @@
1
1
  **Launch prompts.** Present one launch prompt for each ticket that keeps work, ready to paste into a fresh session: With two pieces, the originating ticket gets one; an umbrella does not get one. Order the prompts by work order: A ticket comes after every ticket that blocks it, and otherwise in the order in which it was created. Render each prompt as a bold heading line, `**{ticket_ref}: {title}** (ready now)` or `(after {blocker_ref} merges)`, followed by a fenced block that contains only the text to paste:
2
2
 
3
- - The entry invocation, which the rule above chooses, as `{entry_skill} with plan: {plan_path}, ticket: {ticket_ref}`, adding any flag that the rule names, and omitting the plan when the ticket does not have one.
3
+ - The entry invocation, which the rule above chooses, as `{entry_skill} with plan: {plan_path}, ticket: {ticket_ref}`, adding any flag that the rule names, omitting any argument that the rule omits, and omitting the plan when the ticket does not have one.
4
4
  - The scope notes that the session needs and that the artifacts do not state, such as "only tasks 2 and 3" or "merge only after `live` contains #N".
5
5
  - The ticket's blockers, by reference.
@@ -4,4 +4,6 @@
4
4
 
5
5
  **Umbrella criterion convention:** When writing an umbrella ticket, whose children do the work, list "Every child is closed" as an acceptance criterion alongside any requirement of its own, so that what completes it is stated rather than inferred. When the split is decided, create a child for every planned piece, so that the criterion cannot hold while a planned piece remains: Link each child to the umbrella as a sub-issue, and through blocked-by relations to the pieces that must be merged before it. Specify the current piece fully, and keep each later piece short: its outcome, a few must-have criteria, and a note that it is refined when its work starts. Never leave a planned piece as an outline in the umbrella's body. To defer a planned piece, close its child as not planned.
6
6
 
7
+ **Findings-batch criterion convention:** When writing a ticket that schedules an assessment or a triage of findings, shape it as [findings batches](../_data/spike-conventions.md#findings-batches) states.
8
+
7
9
  **Data-change criterion convention:** When writing a ticket that changes the shape of persisted data or writes to shared state, consult {rulebook:shared-data-conventions}. Scope the ticket to one step of the expand, migrate, contract sequence, and include a criterion that deployed code keeps working whichever happens first, the deploy or the migration. When the ticket adds or changes a skill that writes to shared state, include a criterion that the skill runs against the real data before merge and stops before the write, and when a verdict from an agent decides that write, a criterion that a script checks the verdict's evidence before the write.
@@ -0,0 +1,102 @@
1
+ ---
2
+ name: analyze-performance
3
+ description: Measure a site's web performance as field data and lab data for mobile and desktop, diagnose the pages that fail a Core Web Vitals threshold from Lighthouse's insights and the repository, and write a findings artifact of improvements ranked by expected effect, each with its evidence, the metric that it moves, and its effort. Use when asked how well a site performs, why it is slow, or what would make it faster.
4
+ user-invocable: true
5
+ ---
6
+
7
+ # Analyze performance
8
+
9
+ Report how a site performs today and which changes would make it faster. A bundled helper measures each page and reduces the runs to medians, threshold classes, field data, and the failing Lighthouse insights merged across pages; you resolve the targets, diagnose what the measurements show, inspect the repository for the causes, and rank the improvements in one findings artifact.
10
+
11
+ The skill does not write anything remote: It does not create a ticket, comment on an issue, or change a deployment. The findings artifact is the input of `triage-spike-findings`, which decides what becomes a ticket.
12
+
13
+ ## Inputs
14
+
15
+ - **The targets**: one or more URLs, or the current repository, as the developer names them.
16
+ - **The private URLs**, optional: URLs that PSI must not be sent, such as a staging site.
17
+ - **The ticket**, optional. Without one in session, {skill:save-artifact} saves the artifacts under the ticket ID that it generates.
18
+
19
+ The Lighthouse CLI needs Node 22.19 or later, `pnpm`, and a local Chrome. Every helper command prints one JSON result. When a result has `ok: false`, stop and report its `error` and `message`. Invoke the helper as:
20
+
21
+ ```bash
22
+ node {harness_home_dir}/skills/analyze-performance/analyze-performance.mjs {command} {flags}
23
+ ```
24
+
25
+ The helper's commands, its tool-selection rule, its thresholds, and its output shapes are documented in the guidance package's `docs/analyze-performance-helper.md`.
26
+
27
+ ## Tools
28
+
29
+ | Tool | Role | Target |
30
+ | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- |
31
+ | PageSpeed Insights API | Lab data from a remote Lighthouse run, with CrUX field data, without a key | A public URL; the helper falls back to the Lighthouse CLI when PSI refuses |
32
+ | Lighthouse CLI | Lab data from a local Chrome | A local or preview URL, a private URL, or a public URL that PSI refused |
33
+ | CrUX API | Field data at the 75th percentile for the URL and the origin | A public URL, when `CRUX_API_KEY` is set |
34
+ | Lighthouse insights | The trace-derived diagnosis in every Lighthouse report: LCP breakdown, render-blocking requests, layout-shift culprits, and the rest | Every measured page |
35
+ | Chrome DevTools MCP server | An interactive trace of one page, for a closer look than the insights give | A page whose insights do not explain a failing metric, when the server is connected |
36
+ | The framework's bundle analyzer, or `source-map-explorer` through an ephemeral runner | The modules that dominate shipped JavaScript | The repository's production build |
37
+ | `curl --head` | Caching, compression, and protocol headers | The production URL, or the local server labelled as local |
38
+
39
+ WebPageTest and sitespeed.io are out of scope: They need a key or a hosted account, and the tools above measure what the findings rank on.
40
+
41
+ ## Process
42
+
43
+ ### 1. Prepare
44
+
45
+ Resolve the ticket directory per {skill:save-artifact}, and create `{ticket_dir}/performance/`. Read the declared stage from `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs`. When `project_sensitivity` is `personal` or `confidential`, pass every URL that is not publicly reachable as `--private`, so that it is never sent to PSI.
46
+
47
+ ### 2. Resolve the targets
48
+
49
+ For a repository target:
50
+
51
+ - **The local build.** Build and serve it by the repository's own production build and serve scripts, such as `build` then `start` or `preview`. Never measure a dev server, whose unminified, unbundled output misreports every metric. When the repository does not have a serve script, serve the build output with a static file server through an ephemeral runner.
52
+ - **The production URL.** When the developer did not name one, look for it in the repository's declarations: a framework's site setting (such as Next.js `metadataBase` or Astro's `site`), a sitemap configuration, `homepage` in `package.json`, a GitHub Pages `CNAME`, or the domains of a linked Vercel project. Record the URL with the file that declares it. When none is declared, measure the local build now and ask for the production URL at the checkpoint.
53
+
54
+ Then choose the pages: one per template, from the sitemap or the routes, at most six unless the developer names more. Record each choice with its template. Pass as `--private` every URL that the developer marks private, every preview deployment URL, and every URL whose page requires sign-in; the helper's host rule covers local addresses.
55
+
56
+ ### 3. Measure
57
+
58
+ Run `collect` with every chosen URL, then `summarize`:
59
+
60
+ ```bash
61
+ node {harness_home_dir}/skills/analyze-performance/analyze-performance.mjs collect \
62
+ --url {url} [--url {url}]... [--private {url}]... --out {ticket_dir}/performance/raw/
63
+ node {harness_home_dir}/skills/analyze-performance/analyze-performance.mjs summarize --in {ticket_dir}/performance/raw/
64
+ ```
65
+
66
+ Save the summary as `{ticket_dir}/performance/summary.json`. `collect` reaches the hosts that the helper doc lists; when the sandbox refuses one, retry through the permission gate rather than measuring less. A page's `fallbackReason` and every line of the summary's `unmeasured` go into the artifact's **Unmeasured** section as they stand.
67
+
68
+ ### 4. Diagnose
69
+
70
+ For each page and form factor, take each metric classed `poor` or `needs-improvement`, in field data first and lab data otherwise, and find its causes:
71
+
72
+ - **Insights.** Read the merged insights whose `savings` name the metric. Open the raw report that an insight's `files` names when the summary does not give enough detail, such as the LCP element or the subparts of the LCP breakdown.
73
+ - **The repository**, when one is in scope. Trace each culprit resource to the source that produces it: a bundle to its dominant modules through the bundle analyzer, an image or a font to where the code loads it and how, and a response to the headers that the server or the hosting configuration sets. Name each source by its path relative to the repository root.
74
+ - **A trace**, when the Chrome DevTools MCP server is connected and a failing metric's insights do not account for it. Record what the trace shows; when the server is not connected, record the gap under **Unmeasured**.
75
+
76
+ Lab TBT stands in for INP, which only field data measures: Report it as a proxy, never as INP.
77
+
78
+ ### 5. Compose the findings
79
+
80
+ Write the findings document with these sections, in this order:
81
+
82
+ 1. **Summary.** One table per page of field data, at URL and origin level for each form factor, and one of lab data, with each metric's value and class. Never merge the two: Field data is what real users met, and lab data is one simulated device. State each page's field-data source, or that field data is unavailable and why.
83
+ 2. **Improvements.** One entry per change, each with:
84
+ - its title;
85
+ - its evidence: the insight ids and culprits, the raw files relative to `{ticket_dir}`, and the repository paths;
86
+ - the metric that it is expected to move, the pages and form factors on which that metric fails, and the expected effect, taken from the insight's estimated saving where one exists;
87
+ - its effort, with its reason: `S` for one file or setting, `M` for several files in one area, `L` for a cross-cutting change or one that needs a design decision.
88
+
89
+ Rank the improvements by the class of the metric that each moves, `poor` before `needs-improvement`, then by estimated saving in the metric's own unit (milliseconds for LCP, FCP, and TBT; the shift score for CLS), then by the number of pages. A byte saving breaks a remaining tie only. An improvement drawn from the repository alone, without an insight, ranks after the insight-backed ones of its class. An improvement that the insights of one page alone support says so.
90
+
91
+ 3. **Unmeasured.** What each missing key, missing production URL, private target, failed run, and unconnected tool left out. When the production URL is unknown, state that field data and production delivery (CDN caching, compression, and time to first byte) were not measured.
92
+ 4. **Method.** The tools with the Lighthouse version, the runs per form factor, each page with its template and its tool, the build and serve commands for a local target, and the date.
93
+
94
+ ### 6. Checkpoint
95
+
96
+ Save the document with {skill:save-artifact} as a ticket-level `performance-findings` artifact, and present the summary tables and the ranked improvements. Ask in one action-items block for approval of the findings, and for the production URL when step 2 did not find one. When the developer supplies a URL, measure it as in step 3, revise the findings, and save the revision before asking again. Revise the ranking on the developer's feedback.
97
+
98
+ <!-- include: ../_partials/action-items.md / -->
99
+
100
+ ### 7. Report
101
+
102
+ Once the developer approves the findings, give the artifact's path and one line of counts: pages measured, metrics failing by class, and improvements by effort. Name {skill:triage-spike-findings} as the next step, with the artifact's path as its input. Improvements above the ceiling of a [findings batch](../_data/spike-conventions.md#findings-batches) are triaged in several batches, each on its own ticket.