codeassembly-guidance 0.7.0 → 0.8.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 +261 -0
- package/CHANGELOG.md +62 -0
- package/README.md +47 -29
- package/bin/codeassembly-validate-preferences.js +2 -8
- package/content/_partials/diff-audit-checklist.md +1 -0
- package/content/_partials/plain-speech.md +2 -2
- package/content/_partials/ticket-assessment.md +3 -3
- package/content/codeassembly-content.yaml +6 -0
- package/content/collections/recommended.md +6 -0
- package/content/collections/williamthorsen.md +2 -1
- package/content/guidance/rulebooks/accessibility-conventions.md +6 -3
- package/content/guidance/rulebooks/cross-repo-migration-conventions.md +27 -0
- package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
- package/content/guidance/rulebooks/visual-design-conventions.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +3 -18
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +6 -2
- package/content/guidance/rulebooks/williamthorsen-visual-design-preferences.md +14 -0
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +5 -3
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -20
- package/content/guidance/shared/AGENTS.md +2 -3
- package/content/scripts/README.md +1 -1
- package/content/scripts/check-branch-currency.mjs +7 -7
- package/content/scripts/check-prose.mjs +38 -38
- package/content/scripts/describe-change.mjs +32 -32
- package/content/scripts/manage-jira-ticket.mjs +148 -146
- package/content/scripts/validate-preferences.mjs +9 -9
- package/content/skills/_data/artifact-conventions.md +3 -3
- package/content/skills/_data/entry-points.md +1 -1
- package/content/skills/_data/reduced-object-relatives.md +15 -0
- package/content/skills/_data/spike-conventions.md +9 -2
- package/content/skills/_data/ticket-evaluation.md +3 -0
- package/content/skills/_partials/implementation-order-list.md +4 -4
- package/content/skills/_partials/merge-settled-criterion.md +1 -0
- package/content/skills/_partials/plan-template.md +1 -1
- package/content/skills/_partials/resolve-plan-and-ticket.md +2 -2
- package/content/skills/_partials/split-ticket-create.md +1 -1
- package/content/skills/_partials/ticket-criteria-conventions.md +2 -0
- package/content/skills/align-ticket-with-implementation/SKILL.md +2 -2
- package/content/skills/analyze-performance/SKILL.md +1 -1
- package/content/skills/assess-code-health/SKILL.md +4 -4
- package/content/skills/assess-code-health/assess-code-health.mjs +20 -20
- package/content/skills/assess-ticket/SKILL.md +3 -1
- package/content/skills/assess-ticket/next-steps-after-assessment.md +11 -14
- package/content/skills/assess-usability/SKILL.md +4 -4
- package/content/skills/capture-event/capture-event.mjs +30 -30
- package/content/skills/capture-lede-decision/SKILL.md +1 -1
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +37 -37
- package/content/skills/collaborate/SKILL.md +1 -1
- package/content/skills/condense-branch/SKILL.md +18 -36
- package/content/skills/condense-branch/condense-branch.mjs +17 -0
- package/content/skills/create-bitbucket-pr/SKILL.md +9 -11
- package/content/skills/create-commit/SKILL.md +1 -1
- package/content/skills/create-devlog/SKILL.md +4 -4
- package/content/skills/create-gh-pr/SKILL.md +9 -11
- package/content/skills/create-pr/SKILL.md +9 -11
- package/content/skills/create-ticket/SKILL.md +22 -15
- package/content/skills/curate-feedback/SKILL.md +2 -2
- package/content/skills/derive-session-context/derive-session-context.mjs +103 -103
- package/content/skills/design-and-plan/SKILL.md +6 -6
- package/content/skills/groom-backlog/groom-backlog.mjs +15 -15
- package/content/skills/implement-plan/SKILL.md +1 -1
- package/content/skills/implementation-order/implementation-order.mjs +29 -29
- package/content/skills/index-prototypes/SKILL.md +2 -2
- package/content/skills/investigate-spike/SKILL.md +3 -3
- package/content/skills/list-gh-progress-items/SKILL.md +36 -0
- package/content/skills/list-gh-progress-items/list-gh-progress-items.mjs +68 -0
- package/content/skills/list-implementation-order/SKILL.md +2 -2
- package/content/skills/merge-bb-pr/SKILL.md +9 -11
- package/content/skills/merge-gh-pr/SKILL.md +9 -11
- package/content/skills/merge-pr/SKILL.md +10 -12
- package/content/skills/plan/SKILL.md +2 -2
- package/content/skills/prepare-prototype-brief/SKILL.md +2 -2
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +22 -22
- package/content/skills/refine-plan/SKILL.md +3 -3
- package/content/skills/refine-prototype/SKILL.md +2 -1
- package/content/skills/respond-to-review/SKILL.md +4 -4
- package/content/skills/review-bb-pr/SKILL.md +1 -2
- package/content/skills/review-branch/SKILL.md +18 -13
- package/content/skills/review-criteria/SKILL.md +1 -1
- package/content/skills/review-gh-pr/SKILL.md +1 -2
- package/content/skills/review-pr/SKILL.md +2 -3
- package/content/skills/revise-prose/revise-prose.mjs +52 -52
- package/content/skills/save-artifact/SKILL.md +4 -6
- package/content/skills/save-plan/SKILL.md +2 -2
- package/content/skills/start-ticket/SKILL.md +1 -1
- package/content/skills/streamline-guidance/streamline-guidance.mjs +24 -24
- package/content/skills/summarize-change/SKILL.md +5 -4
- package/content/skills/summarize-chat/SKILL.md +2 -2
- package/content/skills/triage-feedback/SKILL.md +2 -2
- package/content/skills/triage-spike-findings/SKILL.md +26 -22
- package/content/skills/triage-spike-findings/triage-spike-findings.mjs +19 -19
- package/content/skills/update-project-guidance/SKILL.md +1 -1
- package/content/skills/wrap-up/SKILL.md +4 -4
- package/content/skills/write-progress-report/SKILL.md +111 -0
- package/content/skills/write-progress-report/write-progress-report.mjs +150 -0
- package/content/subagents/disposition-challenger.md +7 -6
- package/content/subagents/entry-drafter.md +2 -0
- package/content/subagents/usability-assessor.md +3 -2
- package/package.json +11 -10
- package/schemas/preferences.v1.json +9 -1
- package/schemas/work-types.v1.json +1 -1
|
@@ -7,11 +7,13 @@ members:
|
|
|
7
7
|
- accessibility-conventions
|
|
8
8
|
- cli-conventions
|
|
9
9
|
- command-output-conventions
|
|
10
|
+
- cross-repo-migration-conventions
|
|
10
11
|
- generated-content-policy
|
|
11
12
|
- machine-readable-output-conventions
|
|
12
13
|
- readme-conventions
|
|
13
14
|
- shared-data-conventions
|
|
14
15
|
- ui-copy-conventions
|
|
16
|
+
- visual-design-conventions
|
|
15
17
|
skills:
|
|
16
18
|
- capture-event
|
|
17
19
|
- capture-feedback
|
|
@@ -25,6 +27,8 @@ Membership is per-artifact and enumerated in full rather than by dependency root
|
|
|
25
27
|
|
|
26
28
|
The skills belong here on different grounds. A rulebook of the personal collection names `capture-feedback` in a body token, and `capture-feedback` names `capture-event` in another. Because a collection cannot be closed over an artifact of lesser standing, both were promoted. `capture-event`'s promotion was forced by that chain rather than chosen on its own merits. It is the one member to re-examine first. `capture-feedback` qualifies on its own terms: It does not name any store, declares the registry needed by a capture, and sends a record to the store that the registry's `feedback_kb` names.
|
|
27
29
|
|
|
30
|
+
`cross-repo-migration-conventions` qualifies on its own terms as well. Each rule that it states follows from a mechanism that any migration across repositories meets, such as a ticket body that freezes once work starts, a session that ends at merge, and a shared host that runs the checks of every repository that uses it, rather than from a preference, and it does not name any author, repository, host, or tracker. Its body does not contain any invocation token, so its closure is empty.
|
|
31
|
+
|
|
28
32
|
`generated-content-policy` qualifies on its own terms too: What it states is a mechanism that every consumer meets, not a preference, and the guidance that a reader needs beyond the trigger is in the linked reference rather than in the ambient body loaded by every session.
|
|
29
33
|
|
|
30
34
|
`accessibility-conventions` also qualifies on its own terms. It states WCAG 2.2 AA, an external standard, and adds floors and rules for interactive controls that do not name any author, repository, or tool. Its body does not contain any invocation token, so its closure is empty.
|
|
@@ -42,3 +46,5 @@ Adding a skill that declares a guidance hook has a drawback that the current mem
|
|
|
42
46
|
`shared-data-conventions` qualifies on its own terms too. It states a standard practice, expand, migrate, contract, the rule that unmerged code does not write to shared state, and the checks that a skill writing to shared state needs before merge, and it does not name any author, platform, or store: Each repository's `AGENTS.md` names its own. Its body does not contain any invocation token, so its closure is empty.
|
|
43
47
|
|
|
44
48
|
`ui-copy-conventions` qualifies on its own terms as well. What it asks of the text on a page follows from who reads that text, the person who returns to the page every week, rather than from a preference, and it does not name any author, repository, product, or tool. A project that has content guidelines of its own names them, and they take precedence. Its invocation tokens name one artifact, `accessibility-conventions`, which is already a member, so admitting it does not add any other artifact to what this collection deploys.
|
|
49
|
+
|
|
50
|
+
`visual-design-conventions` qualifies on its own terms as well. What it asks of a page's marks, spacing, alignment, and roles follows from how a reader sees a page's structure before reading its text, rather than from a preference, and it leaves taste to each author's own rulebooks. It does not name any author, repository, product, or tool, and a project's design system takes precedence. Its invocation tokens name one artifact, `accessibility-conventions`, which is already a member, so admitting it does not add any other artifact to what this collection deploys.
|
|
@@ -11,6 +11,7 @@ members:
|
|
|
11
11
|
- williamthorsen-ticketing-preferences
|
|
12
12
|
- williamthorsen-tooling-preferences
|
|
13
13
|
- williamthorsen-typescript-preferences
|
|
14
|
+
- williamthorsen-visual-design-preferences
|
|
14
15
|
- williamthorsen-workflow-preferences
|
|
15
16
|
- williamthorsen-writing-preferences
|
|
16
17
|
skills:
|
|
@@ -19,7 +20,7 @@ members:
|
|
|
19
20
|
|
|
20
21
|
# William Thorsen
|
|
21
22
|
|
|
22
|
-
The personal collection. Membership claims that an artifact was examined and found deliberately fitted to one author rather than generally applicable. What disqualifies each member from `recommended` is the reason it belongs here: The
|
|
23
|
+
The personal collection. Membership claims that an artifact was examined and found deliberately fitted to one author rather than generally applicable. What disqualifies each member from `recommended` is the reason it belongs here: The ten rulebooks state one author's preferences as rules that another team would decide differently, and `people-report` serves a domain in which one author works rather than one that every project shares.
|
|
23
24
|
|
|
24
25
|
Its closure contains `capture-feedback` and `capture-event` in `recommended` and nothing else, which makes declaring it safe alongside the public collection.
|
|
25
26
|
|
|
@@ -1,12 +1,14 @@
|
|
|
1
1
|
---
|
|
2
2
|
slug: accessibility-conventions
|
|
3
|
-
description: 'Accessibility of interfaces: usability before style, contrast and size floors for text, the placement, model, and states of interactive controls, the states for which a reader scans a list, and the browser check of a visible change. Consult before writing an artifact page, a prototype, or a mockup, before designing or placing a control that opens a region or toggles a setting, before designing or reviewing a list, a table, or another surface of repeated items, before defining or changing colour tokens, before writing CSS or a UI component, and before finishing or reviewing a change to a visible component.'
|
|
3
|
+
description: 'Accessibility of interfaces: the aim beyond the floors, usability before style, contrast and size floors for text, the placement, model, and states of interactive controls, the explanation of an action''s consequence at the control, the states for which a reader scans a list, and the browser check of a visible change. Consult before writing an artifact page, a prototype, or a mockup, before designing or placing a control that opens a region or toggles a setting, before designing or reviewing a list, a table, or another surface of repeated items, before defining or changing colour tokens, before writing CSS or a UI component, and before finishing or reviewing a change to a visible component.'
|
|
4
4
|
delivery: [skill]
|
|
5
|
-
version: '
|
|
5
|
+
version: '6'
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# Accessibility conventions
|
|
9
9
|
|
|
10
|
+
The rules below are floors. Aim beyond them, for an interface with which its users work confidently and that they enjoy using, and reach it by following a good established model, as the named-model rule states.
|
|
11
|
+
|
|
10
12
|
Make an interface usable before making it look refined, and when a style choice conflicts with readability or usability, choose usability whatever the aesthetic: "Subtle" and "refined" never justify small or faint text. These conventions apply to a prototype or a mockup exactly as they apply to a released interface.
|
|
11
13
|
|
|
12
14
|
The standard is WCAG 2.2 AA. This rulebook restates only the values that an agent checks while authoring and the rules that WCAG does not set; for everything else, follow WCAG.
|
|
@@ -23,6 +25,7 @@ Check contrast whenever colour tokens are defined or changed. Compute the WCAG c
|
|
|
23
25
|
|
|
24
26
|
- **Named model.** Before designing an affordance, name the established model that the feature most resembles, such as a browser's developer tools, an editor's side panel, or a panel that the product already has, and follow it. Depart from the model only for a reason, and record the reason wherever the design is recorded. Example: An activity drawer follows the editor side-panel model.
|
|
25
27
|
- **Placement.** A control that opens or closes a region sits at that region's edge or in a persistent toolbar, never in an unrelated group of actions. Example: ❌ An "Activity" button among the page header's actions opens a drawer on the right. ✅ The toggle sits at the right end of the toolbar, on the drawer's side.
|
|
28
|
+
- **Consequence at the control.** An action whose consequence is not evident from its label, especially one that publishes, deletes, or hands work to a later step, explains that consequence where the control is, and not only in external documentation. The consequence is not evident when a user who has not read the documentation could not say what the action changes, who sees the result, or whether it can be undone. The explanation of an action that cannot be undone is visible at rest: a helper line beside the control, or, for an action repeated on every row of a list, one line where the list starts. The explanation of an action that can be undone may instead sit in a toggletip: a button beside the control that shows the explanation on click, Enter, and tap, and hides it on Escape. A tooltip that opens only on hover never carries the explanation alone, because touch users and many keyboard users cannot open it, and content that appears on hover or focus meets SC 1.4.13. The control names its explanation through `aria-describedby`. Render every explanation in a product through one shared component, so that every control explains itself the same way. Example: ❌ Each row of a review queue shows Publish and Reject, and nothing more. ✅ One line above the queue states that Publish shows the item to every reader of the site and cannot be undone.
|
|
26
29
|
|
|
27
30
|
## Glanceable state
|
|
28
31
|
|
|
@@ -53,6 +56,6 @@ Put the states in a base style or a shared component rather than setting them at
|
|
|
53
56
|
|
|
54
57
|
## Checking in a browser
|
|
55
58
|
|
|
56
|
-
Check every change to a visible component in a browser before reporting it finished or reviewed. Open the page, then hover over and tab through each new or changed interactive element, and confirm the three states above, or their absence on a disabled element. Toggle each control that toggles, and confirm its on state and its off state. Confirm that each button outside a toolbar has its border or fill at rest, and scan each new or changed list to confirm that its scanned states are visible without reading each item. A test that renders HTML, or a reading of the diff, does not replace this check: Neither shows what the element looks like under the pointer or with focus.
|
|
59
|
+
Check every change to a visible component in a browser before reporting it finished or reviewed. Open the page, then hover over and tab through each new or changed interactive element, and confirm the three states above, or their absence on a disabled element. Toggle each control that toggles, and confirm its on state and its off state. Confirm that each action whose consequence is not evident has its explanation, visible at rest when the action cannot be undone, and otherwise reachable by keyboard and under touch emulation. Confirm that each button outside a toolbar has its border or fill at rest, and scan each new or changed list to confirm that its scanned states are visible without reading each item. A test that renders HTML, or a reading of the diff, does not replace this check: Neither shows what the element looks like under the pointer or with focus.
|
|
57
60
|
|
|
58
61
|
When a browser is not available, report that the check did not run and name the elements that it would have covered. Never report it as passed.
|
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
---
|
|
2
|
+
slug: cross-repo-migration-conventions
|
|
3
|
+
description: 'A migration that spans repositories, such as a move to a new runtime version or convention: one umbrella ticket with a child per repository, shared runtimes moved first, the umbrella''s comments as the ledger of lessons, contract changes decided before any child acts, and what each child reads, posts, and verifies. Consult before creating an umbrella ticket for such a migration, or a child of one.'
|
|
4
|
+
delivery: [skill]
|
|
5
|
+
version: '1'
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Cross-repo migration conventions
|
|
9
|
+
|
|
10
|
+
A migration that spans repositories moves each repository to the same new version or convention, such as a runtime upgrade. The ticketing preferences already give each repository its own ticket and record the order as blocked-by relations, upstream first; the rules below add what such a migration needs beyond that.
|
|
11
|
+
|
|
12
|
+
## The umbrella
|
|
13
|
+
|
|
14
|
+
- **Children.** The umbrella has one child per repository, linked as a sub-issue, and "Every child is closed" as its acceptance criterion.
|
|
15
|
+
- **Shared runtimes first.** A runtime that several repositories use, such as a reusable CI workflow, a shared host that runs checks, or the toolchain installed on each machine, is upstream of every repository that uses it, and its child blocks theirs. When the shared runtime can read each repository's pin, as a reusable workflow can, its child makes it do so, and each repository then moves with its own child. A runtime with one version for every repository, such as a shared host, moves every repository that uses it, including those that have not moved yet; the child that moves it states so on the ledger.
|
|
16
|
+
- **The ledger.** The umbrella's comments record what each child found. A ticket is readable and writable from a session in any repository, so the ledger does not need a branch in a shared repository, and a comment can be added after the umbrella's body is frozen by the start of work. The body states the plan; the comments state what the plan met.
|
|
17
|
+
- **Per-machine steps.** A step that each machine needs follows [who applies the change](../../skills/_data/design-priorities.md#who-applies-the-change). When it reaches the script rung, post the script on the ledger as well as committing it, and open a ticket for each machine that has not run it.
|
|
18
|
+
|
|
19
|
+
## Contract changes
|
|
20
|
+
|
|
21
|
+
The umbrella decides a step that changes a published contract, such as a package's supported runtime floor, before any child acts on it: It states the problem that the step solves, weighs a step that keeps the contract against it, such as testing the claim that the floor makes, and counts the consumers outside the migrated repositories as well as those inside. A contract change found wrong after children have executed it costs a revert in each repository that executed it, and a release for each one that published it. When the umbrella reverses such a decision, it closes the children not yet done as not planned and adds the reverts as children.
|
|
22
|
+
|
|
23
|
+
## Each child
|
|
24
|
+
|
|
25
|
+
- **Before the work.** The child reads the ledger, and its `## Context` names the lessons that apply to its repository and those that do not, with the fact that rules each one out.
|
|
26
|
+
- **The ledger comment.** The child posts its comment before merge, naming its pull request: Merging closes the child, and the session that merges ends there, so a comment due after merge is the one that gets skipped. The comment states what broke and how it was fixed, or that nothing did, and each fact on which a later repository can act. The comment leaves out the lessons that did not apply, because the child's `## Context` already records them. A fact learned after merge goes in a later comment. A rollout step that follows the merge as planned is named in the comment with its command, and a later comment reports its result. A comment that narrows or corrects an earlier lesson links to the comment that it revises.
|
|
27
|
+
- **Verification.** Each check that the comment reports names the runtime on which it ran. A check delegated to a shared host runs on that host's runtime, which may not be the version that the repository pins; a child verifying its own move runs the check where that version is installed, or relies on CI that installs it.
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
slug: ui-copy-conventions
|
|
3
3
|
description: 'Text in a product surface: written for the person who returns to the page, with rules for labels, helper text, errors, and empty states, and a copy budget. Consult before writing labels, helper text, messages, or empty states for a page, a prototype, or a UI component.'
|
|
4
4
|
delivery: [skill]
|
|
5
|
-
version: '
|
|
5
|
+
version: '3'
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# UI copy conventions
|
|
@@ -14,7 +14,7 @@ When a project names its own content guidelines, such as a design system's, thos
|
|
|
14
14
|
## Rules
|
|
15
15
|
|
|
16
16
|
- **Labels** are nouns. **Buttons** are verbs that name the action that they perform, except a toggle, whose label names what it governs and stays the same in both states, as {rulebook:accessibility-conventions} states.
|
|
17
|
-
- **Helper text** states a constraint or a consequence: the format that a field accepts, or what an action changes.
|
|
17
|
+
- **Helper text** states a constraint or a consequence: the format that a field accepts, or what an action changes. The explanation that the consequence-at-the-control rule of {rulebook:accessibility-conventions} requires states what the action changes, who sees the result, and whether it can be undone, and it counts toward the copy budget's one line of helper text.
|
|
18
18
|
- **An error** names the problem and the fix.
|
|
19
19
|
- **Register.** A sentence never explains the page, reassures, congratulates, or narrates the reader ("you are done", "you can…").
|
|
20
20
|
- **Minimizers.** Leave out "simply" and "just".
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
---
|
|
2
|
+
slug: visual-design-conventions
|
|
3
|
+
description: 'Visual design of interfaces: marks for the exception, colour as an encoding channel, padding inside bounded containers, alignment, an appearance that follows each element''s role, tags, product identity, and the browser check of a visible change. Consult before writing an artifact page, a prototype, or a mockup, before writing CSS or a UI component, and before finishing or reviewing a change to a visible component.'
|
|
4
|
+
delivery: [skill]
|
|
5
|
+
version: '2'
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# Visual design conventions
|
|
9
|
+
|
|
10
|
+
A reader sees a page's structure through its marks, its spacing, and its alignment before reading its text. These conventions state the principles that hold whatever the style; a taste, such as one colour scheme over another, does not belong here. They apply to a prototype or a mockup exactly as they apply to a released interface, and {rulebook:accessibility-conventions} sets the floors beneath them.
|
|
11
|
+
|
|
12
|
+
When a project names its own design system, that system takes precedence where the two conflict.
|
|
13
|
+
|
|
14
|
+
## Marks
|
|
15
|
+
|
|
16
|
+
A mark, such as bold, italics, a colour, a highlight, or a badge, is for the exception, and the common state is unmarked. A mark that covers most of a text distinguishes nothing, and the reader can no longer find what it was meant to set apart. The glanceable-state rule of {rulebook:accessibility-conventions} names the states that a list marks. Example: ❌ Every term in a paragraph is bold. ✅ Only the term that the paragraph defines is bold.
|
|
17
|
+
|
|
18
|
+
## Colour as encoding
|
|
19
|
+
|
|
20
|
+
Colour is an encoding channel: Use it to tell kinds and states apart, rather than leaving weight and style to do all the work. Pair each colour with a second cue, as the glanceable-state rule of {rulebook:accessibility-conventions} requires. Example: ❌ Errors, warnings, and notes differ only in weight and italics. ✅ Each has a colour and an icon of its own.
|
|
21
|
+
|
|
22
|
+
## Spacing
|
|
23
|
+
|
|
24
|
+
Text never touches the edge of a container that has a visible boundary, such as a border or a fill: Padding separates the text from every edge. A container without a visible boundary does not have an edge that the text could touch. Example: ❌ A badge's label runs into its border. ✅ The label has padding on every side.
|
|
25
|
+
|
|
26
|
+
## Alignment
|
|
27
|
+
|
|
28
|
+
Every block aligns with an edge or an axis of another block on the page. A block does not float in the vertical middle of a region that it does not fill: It starts where the region's content starts, and an empty state sits where the content that it replaces would begin. A dialog centred in the viewport over the page is not such a block. Example: ❌ An empty-list message floats in the middle of a tall panel, aligned with nothing. ✅ The message starts at the top of the panel, on the list's left edge.
|
|
29
|
+
|
|
30
|
+
Within a block, text and elements are start-aligned, so that each one shares an edge with its neighbours: Everything aligns with something. A column of numbers aligns on its end edge instead, so that digits of the same place value line up. Centring is the rare exception, and it is permitted only for a dialog centred in the viewport, as above, a short single-line label inside a button or a tag, and an icon in a square control. Centred multi-line text never qualifies: Each of its lines starts at a different place, and the reader's eye has to find each start. Example: ❌ A dialog centres its heading and its three-line body, and each line starts at a different place. ✅ The heading and the body start on the dialog's left edge.
|
|
31
|
+
|
|
32
|
+
## Roles
|
|
33
|
+
|
|
34
|
+
The element follows semantics, and the appearance follows the role:
|
|
35
|
+
|
|
36
|
+
- **Link.** An `<a>` navigates, and a text link looks like a link: a colour that sets it apart from the text around it, with a cue beyond colour, such as an underline.
|
|
37
|
+
- **Navigation item.** An item of a navigation bar or a menu looks like navigation: It sits in the navigation region, and the item for the current view is marked.
|
|
38
|
+
- **Button.** A `<button>` acts, and it looks like a button, as the interaction-state rules of {rulebook:accessibility-conventions} state.
|
|
39
|
+
- **Tag.** A value that tags or classifies an item, such as a status or a category, looks like a tag: a compact shape with a fill or a border, set apart from the body text.
|
|
40
|
+
|
|
41
|
+
Example: ❌ "View details" and "Delete" are both blue underlined text. ✅ "View details" is a link to the detail view, and "Delete" is a button.
|
|
42
|
+
|
|
43
|
+
## Identity
|
|
44
|
+
|
|
45
|
+
The product's name and a link to its home view are visible on every view. A product does not ship a template's placeholder identity, such as the template's favicon.
|
|
46
|
+
|
|
47
|
+
## Checking in a browser
|
|
48
|
+
|
|
49
|
+
Check every change to a visible component in a browser before reporting it finished or reviewed, alongside the check in {rulebook:accessibility-conventions}. On each new or changed view, confirm each of these:
|
|
50
|
+
|
|
51
|
+
- The text in each bordered or filled container has padding on every side.
|
|
52
|
+
- Each block aligns with another block, and each block that does not fill its region starts where the region's content starts.
|
|
53
|
+
- Text and the elements within each block are start-aligned, a column of numbers is end-aligned, and centred text appears only in a button's or a tag's single-line label.
|
|
54
|
+
- Marks fall on exceptions only.
|
|
55
|
+
- Each link, navigation item, button, and tag looks like its role.
|
|
56
|
+
- The product's name and home link are visible, and the favicon is the product's own.
|
|
57
|
+
|
|
58
|
+
A reading of the diff does not replace this check: Padding and alignment show only once the page renders. When a browser is not available, report that the check did not run and name the views that it would have covered. Never report it as passed.
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
slug: williamthorsen-collaboration-preferences
|
|
3
3
|
description: William Thorsen's personal preferences for how an agent collaborates -- the persona that it adopts, and the form that its prompts take.
|
|
4
4
|
delivery: ambient
|
|
5
|
-
version: '
|
|
5
|
+
version: '19'
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# William Thorsen's collaboration preferences
|
|
@@ -28,21 +28,11 @@ A question receives an answer, not a procedure for the developer to run: When th
|
|
|
28
28
|
|
|
29
29
|
Hand over a part that takes more than one command as one paste-ready script, which runs every step, cleans up after itself, and prints only the facts that you need, so that the developer pastes once and replies once. Never build up a check by asking for one command per turn. When the developer's shell can read your files, also write the script to a file and give its path, so that the developer can rerun the check without pasting it again. Before running or handing over a check of a GUI application, confirm which machine your commands run on, such as by comparing `hostname` with the machine that displays the application, rather than assume that the two are the same.
|
|
30
30
|
|
|
31
|
-
The handoff has a recognizable sign. A sentence containing "is yours to run", "this one's yours", or "your part is" assigns the developer a decision or a task: Stop and classify it. Give a decision your recommendation and its reason,
|
|
31
|
+
The handoff has a recognizable sign. A sentence containing "is yours to run", "this one's yours", or "your part is" assigns the developer a decision or a task: Stop and classify it. Give a decision your recommendation and its reason, and take a task up the ladder. Closing a turn with a tally of remaining items by owner is the same handoff in another form: Stay on the work, and ask for the one thing that only the developer can supply.
|
|
32
32
|
|
|
33
33
|
## Prompt formatting
|
|
34
34
|
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
The gated class is closed: the shape of a public API or a contract; remote shared state, such as a ticket edit, a push, a merge, or the creation of a branch or a ticket; data loss or any action that cannot be undone; spend or budget; and a preference for which you do not have any evidence, which includes a templated next-steps menu. Decide everything else yourself by default; verification is never in the class. Never decide a gated action in your own voice: The developer authorizes it; recommend, build on the recommendation provisionally, and ask at the checkpoint. Building on it means doing the work that depends on the answer; do not take the gated action itself until the developer authorizes it.
|
|
38
|
-
|
|
39
|
-
Proceed provisionally: Do everything that does not depend on an answer first, and raise an ask only when the work is blocked or at the checkpoint. In a skill without a phase structure, or in work outside a skill, treat the skill's own approval gate, or the end of the work, as the checkpoint. Collect the asks that survive the gate into one review at the checkpoint, never one per turn. Write every decision that you take in place of an ask into the plan's `## Decisions taken` section with its one-line reason, or into the turn's summary when the work does not have a plan; a silent decision is worse than an ask. Start each line that states a decision awaiting the checkpoint with 🔲, in the record and in a turn's narrative alike, and drop the marker once the developer approves the checkpoint at which you presented the decision.
|
|
40
|
-
|
|
41
|
-
Never rank the options by your own elapsed time, round trips, or effort. You measure all three yourself, and that measure counts the developer's context switch and review cycles as nothing, so measuring one does not make the call yours, and a more accurate measurement still cannot rank them. Ordering follows from this: When the order changes the code or the total effort, recommend it and mark it, naming the delay that it causes and saying nothing about delay when none is involved; when the outcomes are identical and only the timing differs, present the delay that each option causes, render the options unmarked, and put the choice at the checkpoint.
|
|
42
|
-
|
|
43
|
-
An ask costs the developer a context switch and idles the session until the answer arrives; a recorded decision costs them a word to overrule. Full spec: [recommendation-gradient.md](../../skills/_data/recommendation-gradient.md).
|
|
44
|
-
|
|
45
|
-
End every response that asks for something with a labelled action-items block that contains every ask and nothing else; when a skill defines its own canonical block for asks, use that block instead. Prose above may discuss; only the block may ask. Before ending a turn, sweep the draft for anything that invites a response: A soft offer -- "let me know if", "say the word and I will", "worth knowing", "I can also" -- is an ask, and leaving it in the narrative is how asks get missed. So is an environment blocker that remains once you climb the ladder in "Handoffs": Ask for the resource that its third rung names, and a blocker left in the prose is a defect. Do not add a block to a response without an ask. When the block has more than one ask, or more than one independently-numbered list, label each with its identifier (`A` for an action, `Q` for a question); a single ask needs none. Full spec: [action-items.md](../../skills/_data/action-items.md).
|
|
35
|
+
An environment blocker that remains once you climb the ladder in "Handoffs" is an ask like any other: Ask for the resource that its third rung names, and a blocker left in the prose is a defect.
|
|
46
36
|
|
|
47
37
|
When the developer signals overload, such as "I can't do this any more" or a count of the commands that they have run, stop adding asks: Do what you can, say once what is left undone, and end the turn without an ask and without an action-items block. Stay in that mode in every later turn until the developer asks for something.
|
|
48
38
|
|
|
@@ -50,15 +40,10 @@ When prompting the user for input, never use interactive UI controls (pop-up, ar
|
|
|
50
40
|
|
|
51
41
|
- **Confirmation prompts** (the user's response is approve-or-redirect; "no" means "let's adjust or discuss," not a concrete alternative action): End with `👍🏼👎🏼`.
|
|
52
42
|
- **All other questions** (open-ended, clarifications): End with `🤔`
|
|
53
|
-
- **Numbered options (2 or more choices)**: Follow the recommendation-gradient convention, marking each option ■■■/■■□/■□□/□□□ at the strength that you actually hold. Bullets report the weight of each option, not a balance between the options, so an uneven menu is the accurate one when the options differ in quality. Write a `➕` or `➖` only when it is real: It must be false for at least one other option, and a reader who believed it must pick differently. State in a `➖` what breaks or what it costs, and for whom; cut one that you cannot state that way, and never keep a minor con by deleting its qualifier. Never add a bullet to fill a slot or to balance the options. Leave an option without a real bullet bare, and when every option lacks one, let the markers alone convey the recommendation. Before rendering, check the leader, in a gated decision as in any other, because the marker tells the developer how much deliberation the ask needs: State as an alternative's `➖` any drawback that disqualifies it, including one that follows from the constraints and acceptance criteria of the work at hand, cut each `➖` on the strongest option that a reader would not act on, mark it ■■■ when every alternative has a disqualifying `➖`, and re-apply the gate. This covers every option-style list with substantive tradeoffs, including templated next-steps menus and yes/no choices in which both paths are concrete actions (rendered as a 2-option gradient list rather than `👍🏼👎🏼`). When a response has 2+ such lists, label each with its identifier (`A1`/`A2` for actions, `Q1`/`Q2` for questions). Full spec: [recommendation-gradient.md](../../skills/_data/recommendation-gradient.md).
|
|
54
43
|
|
|
55
44
|
Examples:
|
|
56
45
|
|
|
57
46
|
- "Do you want me to start implementation? 👍🏼👎🏼"
|
|
58
|
-
- "Does this design look correct? 👍🏼👎🏼"
|
|
59
|
-
- "Should I proceed with this approach? 👍🏼👎🏼"
|
|
60
|
-
- "Apply these revisions (say no if you'd like to adjust something else first)? 👍🏼👎🏼"
|
|
61
47
|
- "Which color scheme would you prefer? 🤔"
|
|
62
|
-
- "What additional features should I include? 🤔"
|
|
63
48
|
|
|
64
49
|
**Comprehension contract for `👍🏼👎🏼`.** If the user clearly affirms ("yes", "looks good", "go ahead", 👍), proceed. If they clearly negate ("no", "stop", 👎), do not. Anything else -- including positive commentary that isn't a clear go-ahead -- is conversation, not inferred approval. Never treat a clear affirmation as ambiguous, and never treat an ambiguous response as a clear affirmation. When in doubt, treat as conversation.
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
slug: williamthorsen-ticketing-preferences
|
|
3
3
|
description: William Thorsen's preferences for how work is split across tickets, how the relationships between them are recorded, and which figures a ticket body states.
|
|
4
4
|
delivery: hook
|
|
5
|
-
version: '
|
|
5
|
+
version: '10'
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# William Thorsen's ticketing preferences
|
|
@@ -13,7 +13,11 @@ When work deserves more than one pull request, give each pull request its own ti
|
|
|
13
13
|
|
|
14
14
|
A piece gets its own ticket when it can be merged and verified on its own, not when it looks large enough to deserve one. When the count is a judgment, cut finer: Merging two tickets that turned out to be one costs an edit and a close, while splitting one that turned out to be four costs a rewrite of the original, new children, a re-cut plan, and whatever was committed against the superseded contract.
|
|
15
15
|
|
|
16
|
-
|
|
16
|
+
Before deciding the ticket count of work that spans several layers or adds a new subsystem, estimate its size: the layers and subsystems that it touches, and the approximate source and test lines. State the estimate wherever the count is decided. When the pieces of such work can each be merged and verified on their own, recommend the split, and do not offer one ticket at equal strength. That only the last piece is visible to a user is not a reason to keep the work whole: An earlier piece is verified through its tests and its API.
|
|
17
|
+
|
|
18
|
+
Adding a package to a monorepo is two tickets. The first adds the empty scaffold with its documentation and its package references, such as the workspace lists, labels, lockfile, README, and identity checks, and it passes the repository's checks on its own. The second adds the package's functionality and is blocked by the first.
|
|
19
|
+
|
|
20
|
+
A ticket covers work in one repository. When a change needs work in two or more repositories, give each repository its own ticket, even when one repository's share is small, and record the merge order, upstream first, as blocked-by relations. The repository boundary does not need a judgment: A pull request lives in one repository, so a ticket that spans two cannot close on a single merge. When the change migrates many repositories to a new version or convention, consult {rulebook:cross-repo-migration-conventions} for the umbrella and its children.
|
|
17
21
|
|
|
18
22
|
This governs work already judged to need more than one pull request. Whether work discovered mid-change becomes a ticket at all is decided first by the fold-in default in [scope-and-deferral.md](../../skills/_data/scope-and-deferral.md).
|
|
19
23
|
|
|
@@ -0,0 +1,14 @@
|
|
|
1
|
+
---
|
|
2
|
+
slug: williamthorsen-visual-design-preferences
|
|
3
|
+
description: 'Visual taste for pages and interfaces: a quiet colour scheme over a monochrome one. Consult before choosing a colour scheme or styling a page, a prototype, or a UI component.'
|
|
4
|
+
delivery: [skill]
|
|
5
|
+
version: '1'
|
|
6
|
+
---
|
|
7
|
+
|
|
8
|
+
# William Thorsen's visual-design preferences
|
|
9
|
+
|
|
10
|
+
Taste that applies on top of {rulebook:visual-design-conventions}, which states the principles that hold whatever the taste. A preference here never relaxes one of those principles.
|
|
11
|
+
|
|
12
|
+
## Colour scheme
|
|
13
|
+
|
|
14
|
+
Prefer a quiet colour scheme to a monochrome one: muted hues on neutral surfaces, each hue encoding a kind or a state. A monochrome scheme leaves weight and style to do all the encoding, which the colour-as-encoding rule of {rulebook:visual-design-conventions} rules out, and a loud scheme spends the reader's attention on decoration.
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
slug: williamthorsen-workflow-preferences
|
|
3
3
|
description: William Thorsen's personal preferences for how work moves -- scope, branches and worktrees, guidance capture, and the arc of product development.
|
|
4
4
|
delivery: ambient
|
|
5
|
-
version: '
|
|
5
|
+
version: '14'
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# William Thorsen's workflow preferences
|
|
@@ -19,13 +19,15 @@ version: '13'
|
|
|
19
19
|
|
|
20
20
|
Never create a branch or worktree without explicit authorization. Each ticket is implemented in its own worktree, and the developer's tooling relies on that: Do all of one ticket's work in that worktree, never switch a worktree to another branch, and start a new session in another ticket's own worktree for work on that ticket. Which branch or worktree a ticket's work uses is settled, so never ask it.
|
|
21
21
|
|
|
22
|
-
|
|
22
|
+
A session works only in its own repository and in its own ticket's worktree. For any other repository or ticket, filing the ticket is the limit of the session's work: Do not create a branch or a worktree there, commit, push, or open a pull request. Reading another repository is not restricted. A request from the developer for that work in this session governs, but a request to file a ticket does not ask for the ticket's work.
|
|
23
|
+
|
|
24
|
+
When a session works in its own ticket's worktree and that worktree is not its cwd, pass that worktree to every skill that takes a working directory, such as `create-commit`, or commit inline with `git -C`: A skill with `context: fork` starts in the session's cwd, and the skill listing does not show which skills fork.
|
|
23
25
|
|
|
24
26
|
After a merge, say nothing about worktree or branch state and never offer to manage it. The worktree stays as long as its branch does, so there is nothing to clean up and nothing to ask about.
|
|
25
27
|
|
|
26
28
|
## Cross-repo sequencing
|
|
27
29
|
|
|
28
|
-
When the work would be better done upstream, in a package or repository on which this one depends, default to upstream first:
|
|
30
|
+
When the work would be better done upstream, in a package or repository on which this one depends, default to upstream first: File the upstream ticket and record it as a blocker of this one, and make the downstream change once the upstream change is merged and published and the dependency is upgraded here. The upstream change belongs to the upstream ticket's own session. Propose that order rather than merging a downstream workaround ahead of it.
|
|
29
31
|
|
|
30
32
|
Downstream first reads as faster because something is merged sooner, but it requires two downstream changes rather than one: the workaround, then its removal once the upstream change is merged. It also forces upstream to decide without the downstream requirement in hand, so upstream cannot weigh that requirement against its own constraints, and may settle on a shape that the consumer keeps working around.
|
|
31
33
|
|
|
@@ -2,7 +2,7 @@
|
|
|
2
2
|
slug: williamthorsen-writing-preferences
|
|
3
3
|
description: William Thorsen's personal writing preferences for agent-authored prose.
|
|
4
4
|
delivery: [ambient, hook]
|
|
5
|
-
version: '
|
|
5
|
+
version: '14'
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
# William Thorsen's writing preferences
|
|
@@ -34,7 +34,7 @@ Don't use em-dashes; use appropriate punctuation instead. A dash separating an i
|
|
|
34
34
|
|
|
35
35
|
<!-- rule: reduced-object-relative 1 -->
|
|
36
36
|
|
|
37
|
-
A relative clause with an object gap takes an overt relativizer: "the source that it names", never "the source it names". The test is mechanical: Between the head noun and the embedded subject, look for `that` or `which`.
|
|
37
|
+
A relative clause with an object gap takes an overt relativizer: "the source that it names", never "the source it names". The test is mechanical: Between the head noun and the embedded subject, look for `that` or `which`. For a gap after a copula, a coordinated gap, or the anaphoric one-series as head, see [rare cases](../../skills/_data/reduced-object-relatives.md).
|
|
38
38
|
|
|
39
39
|
**Repairs, in preference order.** Choose per site; restored relativizers stacked across a passage read as a tic of their own.
|
|
40
40
|
|
|
@@ -44,20 +44,9 @@ A relative clause with an object gap takes an overt relativizer: "the source tha
|
|
|
44
44
|
|
|
45
45
|
**A gap in a prepositional phrase takes its own order.** Pied-pipe the preposition first: "the level against which it is probed", preferred over the stranded "the level that it is probed against". If pied-piping reads stiffly, the stranded relativizer is the second choice and a recast the third. The passive participle is last here rather than first, since the actor is already inside the clause.
|
|
46
46
|
|
|
47
|
-
**
|
|
47
|
+
**The agentive `by`-phrase satisfies plain speech.** Plain speech rejects the _agentless_ passive that hides who acted. A `by`-phrase names the actor in the same phrase; therefore, "imported by every exported tier module" satisfies plain speech as fully as the active form does.
|
|
48
48
|
|
|
49
|
-
**
|
|
50
|
-
|
|
51
|
-
**The shapes, ranked from worst to mildest.** The rank follows the embedded subject's form, since the reader must keep that form in mind until the verb appears. Each is an exhibit of the construction, not a model to copy.
|
|
52
|
-
|
|
53
|
-
1. **Quantified noun phrase** (worst): "a dependency every exported tier module imports". The reader absorbs a quantifier and a full noun phrase before any verb discharges the head.
|
|
54
|
-
2. **Definite noun phrase**: "the ticket the branch name encodes".
|
|
55
|
-
3. **Bare noun**: "an idiom developers recognize".
|
|
56
|
-
4. **Pronoun** (mildest): "the source it names". Forbidden all the same; a pronoun shortens the wait rather than ending it.
|
|
57
|
-
|
|
58
|
-
**The agentive `by`-phrase satisfies plain speech.** Plain speech rejects the _agentless_ passive that hides who acted. A `by`-phrase names the actor in the same phrase; therefore, "imported by every exported tier module" satisfies plain speech as fully as the active form does. This rule breaks the habit of using a contact clause to avoid a passive that was never the target.
|
|
59
|
-
|
|
60
|
-
**Scope.** The rule governs a lexical head noun whose relative clause has a gap in an argument position: the direct object ("the source that it names"), the object of a preposition ("the level against which it is probed"), or the complement of a copula ("the throwing mock that it is"). The anaphoric one-series heads a relative clause under the rule too, though it is not a lexical noun, because a relativizer restores to it: "one that the spy carries". Two neighboring constructions fall outside the rule, each on a ground of its own: the fused head ("everything I know", "all you need"), which is its own relative pronoun and does not admit a relativizer, and the adjunct relative ("the reason it fails", "the way it works"), whose gap does not fill an argument position. The boundary keys on head type and gap role. Neither a short embedded subject nor a tight word budget exempts anything.
|
|
49
|
+
**Scope.** The rule governs a lexical head noun whose relative clause has a gap in an argument position: the direct object ("the source that it names"), the object of a preposition ("the level against which it is probed"), or the complement of a copula ("the throwing mock that it is"). Two neighboring constructions fall outside the rule, each on a ground of its own: the fused head ("everything I know", "all you need"), which is its own relative pronoun and does not admit a relativizer, and the adjunct relative ("the reason it fails", "the way it works"), whose gap does not fill an argument position. Neither a short embedded subject nor a tight word budget exempts anything.
|
|
61
50
|
|
|
62
51
|
## Second person
|
|
63
52
|
|
|
@@ -71,10 +60,7 @@ Imperative mood is untouched, because it does not contain a pronoun: "Run the fo
|
|
|
71
60
|
|
|
72
61
|
**The replacement names an actor.** Say who or what acts: "the config sets a cap on the rule" rather than "you cap the rule". If an actor does not belong in the sentence, recast so that the artifact is the subject of a verb that it performs or one that states a relation, as plain speech requires: "the flag takes a path" rather than "you pass it a path".
|
|
73
62
|
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
- **The agentless passive.** Dropping the pronoun by hiding who acted trades one defect for another: "your rules are capped" becomes "the rules are capped", which names nobody. Plain speech rejects that passive; name the actor instead.
|
|
77
|
-
- **The surviving object gap.** "the cap you set" and "the cap the config sets" are the same reduced object relative; therefore, the substitution leaves the second defect in place. Restore the relativizer, or apply the repairs in "Reduced object relatives" above.
|
|
63
|
+
Dropping the pronoun by hiding who acted trades one defect for another: "your rules are capped" becomes "the rules are capped", which names nobody. Plain speech rejects that passive; name the actor instead.
|
|
78
64
|
|
|
79
65
|
## Sentence case
|
|
80
66
|
|
|
@@ -83,7 +69,6 @@ A naive substitution fails in two ways:
|
|
|
83
69
|
Use sentence case for titles, headings, section headers, steps, labels, and interface elements. Never use title case. Preserve the case of proper nouns, named entities, and the actual titles of books and movies.
|
|
84
70
|
|
|
85
71
|
- "Backend: Express API routes and server" not "Backend: Express API Routes And Server"
|
|
86
|
-
- "Frontend: Static Excalibur scene" not "Frontend: Static Excalibur Scene"
|
|
87
72
|
- "Customizing the Status Adapter for a new backend", not "Customizing the Status Adapter for a New Backend"
|
|
88
73
|
|
|
89
74
|
## `so` and other connectives
|
|
@@ -59,8 +59,7 @@ That restraint on editing a record applies to the remote ticket as well, from th
|
|
|
59
59
|
|
|
60
60
|
From that point on, the ticket's `## Problem`, `## Context`, and `## Proposed solution` record what was known and proposed when the work began, so they are never revised toward the outcome: A proposal does not become wrong because the implementer did something else, and revising it destroys the only record of what was foreseen. Report a divergence between one of those sections and the implementation in the pull-request description's `## Notes for reviewers` only when it changes what a reviewer checks, per the reader test that `summarize-change` states, and state it as the current fact rather than as a departure from the ticket.
|
|
61
61
|
|
|
62
|
-
Acceptance criteria are the one revisable part, because they alone are the contract that an implementation can falsify. Align them to the implementation only when the two conflict, or when the gap would mislead a reviewer.
|
|
63
|
-
|
|
62
|
+
Acceptance criteria are the one revisable part, because they alone are the contract that an implementation can falsify. Align them to the implementation only when the two conflict, or when the gap would mislead a reviewer.
|
|
64
63
|
A write that this section rules out is not a skipped step, because nobody asked for it, and it does not produce any user-facing text: Do not mention the doctrine or the marker, do not report the write that was not made, and do not offer to reconcile the record with current state. When the user asks for such a write, decline it in one line and name the alternative: for a revision that you publish, a new record; for a divergence from the ticket, the pull-request description; for a lede that the records do not contain, `capture-lede-decision`'s `--agent-lede-file` and `--merged-lede-file`. A human's later edit to a published body does not need a record, because the `merge` record captures what merged.
|
|
65
64
|
|
|
66
65
|
## Documentation placement
|
|
@@ -75,4 +74,4 @@ Agents write most of what appears under the developer's account, so a creator, r
|
|
|
75
74
|
|
|
76
75
|
## Commits
|
|
77
76
|
|
|
78
|
-
Invoke the `create-commit` skill to make a commit.
|
|
77
|
+
Invoke the `create-commit` skill to make a commit. A title rendered from the configured template is correct: Never propose changing it to match other commits, and do not comment on whether it contains a ticket reference.
|
|
@@ -33,7 +33,7 @@ Prose mentions of script names that are not invocations (e.g., ``"the `describe-
|
|
|
33
33
|
- `check-prose.mjs`: Runs every `revise-prose` detector over one Markdown file at any path, without reading or writing the sweep record, and prints one line per candidate, or one JSON document `{ file, rules, candidates }` under `--json`. It exits 0 without candidates, 1 with candidates, and 2 on a usage error or an unreadable file. Invoke it as `node {harness_home_dir}/scripts/check-prose.mjs --file <path> [--json]`; `summarize-change` runs it over a change summary's prose.
|
|
34
34
|
- `describe-change.mjs`: Renders titles for commits, tickets, PRs, and merges from declarative templates, the `{breaking}` marker included, reads a rendered title back into its parts, consolidates a commit range's entries into a consolidated record, applies overrides to a record, renders the fenced `change-record` block that ends a pull-request body and the `## Details` body of a change summary, and resolves what a pull request merges as from that block and the pull request's commits. Invoke it as `node {harness_home_dir}/scripts/describe-change.mjs <subcommand>`, where [title-templates.md](../skills/_data/title-templates.md#invoking-the-bundle) names the subcommand for each; the bundle does not have a shebang.
|
|
35
35
|
- `get-ticket-id.sh`: Extracts a ticket ID from a branch name.
|
|
36
|
-
- `manage-jira-ticket.mjs`: Compares `acli`'s active site with a ticket's site and names the `acli jira auth switch` command on a mismatch (`check-site`), resolves the project key and issue type for a Jira work item from the repository's `.agents/preferences.yaml` (`resolve-target`), converts a Markdown body to ADF with task lists as native task items (`convert-body`),
|
|
36
|
+
- `manage-jira-ticket.mjs`: Compares `acli`'s active site with a ticket's site and names the `acli jira auth switch` command on a mismatch (`check-site`), resolves the project key and issue type for a Jira work item from the repository's `.agents/preferences.yaml`, taking `integrations.jira.umbrella_issue_type` for an umbrella under `--umbrella` and `integrations.jira.subtask_issue_type` for a child of a level-0 parent under `--parent-level` (`resolve-target`, and `create` likewise, from its parent's level), converts a Markdown body to ADF with task lists as native task items (`convert-body`), creates a work item through `acli` exactly once, checking its parent first (`create`), and closes a work item (`close`): It posts a Markdown body as a comment unless a comment already opens with the body's first line, then transitions the item to the repository's `integrations.jira.done_status` unless its status category is done. `create` and `close` refuse before any other `acli` call when `ticket.base_url` is set, in the repository's preferences or the global file, and `acli`'s active site is another site or cannot be read. Invoke it as `node {harness_home_dir}/scripts/manage-jira-ticket.mjs <subcommand>`.
|
|
37
37
|
- `resolve-review-run.mjs`: Finds a ticket's active review run (its newest `interactive` run directory), opens it for a new review by creating one when none exists, or finds the newest reviewer or overseer review in it. Invoke it as `node {harness_home_dir}/scripts/resolve-review-run.mjs active|open|latest`.
|
|
38
38
|
- `resolve-frontmatter.sh`: Emits canonical artifact frontmatter (YAML or JSON) with provenance, ticket, branch, commit, and PR fields, plus scalar and list extension keys.
|
|
39
39
|
- `select-lede-exemplars.mjs`: Selects author-approved ledes of a given work type from the lede-decision corpus, optionally floored at a quality rating. `--breaking` marks the request as one for a breaking change, as a `!` on `--type` does: An unmarked request never selects a breaking record, and a marked one prefers breaking records within each widening step. `--with-pair` reports each record's agent lede, merged lede, and author comment alongside the approved text.
|
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
import { createRequire as __cjsCreateRequire } from 'node:module';
|
|
2
2
|
const require = __cjsCreateRequire(import.meta.url);
|
|
3
|
-
var R=Object.defineProperty;var t=(n,e)=>R(n,"name",{value:e,configurable:!0});import g from"node:process";function b(n){return n instanceof Error||Object.prototype.toString.call(n)==="[object Error]"}t(b,"isError");function
|
|
4
|
-
`),!0}}t(w,"isEntryPoint");function E(n,e){let r=[],o=[];for(let
|
|
5
|
-
`).map(a=>V(a));if(r.length===0)return c.map(a=>({...a,touchesWork:null}));let u=r.map(a=>`:(top,literal)${a}`),
|
|
6
|
-
`));return c.map(a=>({...a,touchesWork:
|
|
7
|
-
`)}catch(n){g.stderr.write(`check-branch-currency: ${
|
|
3
|
+
var R=Object.defineProperty;var t=(n,e)=>R(n,"name",{value:e,configurable:!0});import g from"node:process";function b(n){return n instanceof Error||Object.prototype.toString.call(n)==="[object Error]"}t(b,"isError");function l(n){try{return b(n)&&typeof n.message=="string"&&n.message!==""?n.message:String(n)}catch{return"[unstringifiable value]"}}t(l,"describeError");import{realpathSync as y}from"node:fs";import x from"node:process";import{fileURLToPath as O}from"node:url";function w(n,e){let r=x.argv[1];if(r===void 0)return!1;try{return y(O(n))===y(r)}catch(o){return x.stderr.write(`${e}: warning: could not determine entry point: ${l(o)}
|
|
4
|
+
`),!0}}t(w,"isEntryPoint");function E(n,e){let r=[],o=[];for(let i=0;i<n.length;i+=1){let c=n[i];if(c===void 0)continue;if(!c.startsWith("--")){r.push(c);continue}let u=B(c,e);if(u===null)throw new Error(`unknown flag: ${c}`);let{spec:s,inlineValue:a}=u;if(!s.takesValue){if(a!==null)throw new Error(`--${s.name} does not take a value`);o.push({name:s.name,value:null});continue}if(a!==null){o.push({name:s.name,value:a});continue}let f=n[i+1]??null;if(f===null||f.startsWith("--"))throw new Error(`--${s.name} requires a value`);o.push({name:s.name,value:f}),i+=1}return{positionals:r,flags:o}}t(E,"scanFlags");function B(n,e){for(let r of e)for(let o of[r.name,...r.aliases??[]]){let i=`--${o}`;if(n===i)return{spec:r,inlineValue:null};if(n.startsWith(`${i}=`))return{spec:r,inlineValue:n.slice(i.length+1)}}return null}t(B,"matchFlag");import{execFileSync as N}from"node:child_process";import j from"node:process";function k(n){return M(n)&&!Array.isArray(n)}t(k,"isRecord");function M(n){return typeof n=="object"&&n!==null}t(M,"isObject");function $(n){let{base:e,cwd:r,paths:o}=n,{remote:i,branch:c}=h(e),u=A(r,i,c);if(!u.ok)return{fetched:!1,error:u.error};let s=p(r,`HEAD..${e}`),a=p(r,`${e}..HEAD`),f=m(r,["status","--porcelain"])==="",F=G(r,e),S=T(r,e,o);return{fetched:!0,base:e,behind:s,ahead:a,clean:f,pushed:F,gained:S}}t($,"checkBranchCurrency");function h(n){let e=n.indexOf("/"),r=n.slice(0,Math.max(0,e)),o=n.slice(e+1);if(e===-1||r===""||o==="")throw new Error(`--base must name a remote and a branch, such as origin/main: ${n}`);return{remote:r,branch:o}}t(h,"splitBase");var v="@{u}";function p(n,e){return Number.parseInt(m(n,["rev-list","--count",e]),10)}t(p,"countCommits");function C(n){let e=k(n)?n.stderr:void 0;return typeof e=="string"&&e.trim()!==""?e.trim():l(n)}t(C,"describeGitFailure");function A(n,e,r){try{return N("git",["-C",n,"fetch","--quiet",e,r],{encoding:"utf8",env:{...j.env,GIT_TERMINAL_PROMPT:"0"},stdio:["ignore","pipe","pipe"]}),{ok:!0}}catch(o){return{ok:!1,error:C(o)}}}t(A,"fetchBranch");function G(n,e){return P(n)?p(n,e+".."+v)>0:!1}t(G,"hasPushedOwnCommits");function P(n){try{return m(n,["rev-parse","--abbrev-ref","--symbolic-full-name",v]),!0}catch{return!1}}t(P,"hasUpstream");function T(n,e,r){let o=`HEAD..${e}`,i=m(n,["log","--format=%H%x09%s",o]),c=i===""?[]:i.split(`
|
|
5
|
+
`).map(a=>V(a));if(r.length===0)return c.map(a=>({...a,touchesWork:null}));let u=r.map(a=>`:(top,literal)${a}`),s=new Set(m(n,["log","--format=%H",o,"--",...u]).split(`
|
|
6
|
+
`));return c.map(a=>({...a,touchesWork:s.has(a.sha)}))}t(T,"listGainedCommits");function V(n){let e=n.indexOf(" ");return{sha:n.slice(0,e),subject:n.slice(e+1)}}t(V,"parseLogLine");function m(n,e){try{return N("git",["-C",n,...e],{encoding:"utf8",stdio:["ignore","pipe","pipe"]}).trim()}catch(r){throw new Error(`git ${e.join(" ")} failed: ${C(r)}`,{cause:r})}}t(m,"readGit");var I=[{name:"base",takesValue:!0},{name:"path",takesValue:!0}],d="usage: check-branch-currency --base <remote>/<branch> [--path <path>]...";function W(){try{let n=H(g.argv.slice(2));g.stdout.write(`${JSON.stringify(n,null,2)}
|
|
7
|
+
`)}catch(n){g.stderr.write(`check-branch-currency: ${l(n)}
|
|
8
8
|
`),g.exit(1)}}t(W,"main");w(import.meta.url,"check-branch-currency")&&W();function H(n){let{flags:e,positionals:r}=E(n,I);if(r.length>0)throw new Error(`unexpected argument: ${r.join(" ")}
|
|
9
|
-
${d}`);let o=e.filter(
|
|
9
|
+
${d}`);let o=e.filter(s=>s.name==="base").map(s=>s.value??""),[i,...c]=o;if(i===void 0)throw new Error(`--base is required
|
|
10
10
|
${d}`);if(c.length>0)throw new Error(`--base may be given only once
|
|
11
|
-
${d}`);h(
|
|
11
|
+
${d}`);h(i);let u=e.filter(s=>s.name==="path").map(s=>s.value??"");return $({base:i,cwd:g.cwd(),paths:u})}t(H,"runCommand");
|