codeassembly-guidance 0.1.0 → 0.2.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 +757 -0
- package/CHANGELOG.md +181 -0
- package/README.md +125 -95
- package/bin/codeassembly-validate-preferences.js +18 -0
- package/content/_partials/README.md +2 -2
- package/content/_partials/code-style.md +1 -1
- package/content/_partials/comment-discipline.md +1 -1
- package/content/_partials/plain-speech-calibration.md +4 -0
- package/content/_partials/technical-recommendations.md +1 -0
- package/content/codeassembly-content.yaml +11 -1
- package/content/collections/all.md +2 -2
- package/content/collections/atlassian.md +2 -1
- package/content/collections/recommended.md +9 -2
- package/content/collections/triage.md +3 -67
- package/content/collections/williamthorsen.md +2 -1
- package/content/guidance/README.md +1 -1
- package/content/guidance/rulebooks/accessibility-conventions.md +23 -5
- package/content/guidance/rulebooks/cli-conventions.md +192 -0
- package/content/guidance/rulebooks/codeassembly-content-specification.md +32 -9
- package/content/guidance/rulebooks/commit-conventions.md +2 -2
- package/content/guidance/rulebooks/live-worktree-policy.md +3 -2
- package/content/guidance/rulebooks/readme-conventions.md +3 -3
- package/content/guidance/rulebooks/shared-data-conventions.md +2 -2
- package/content/guidance/rulebooks/shell-conventions.md +17 -23
- package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +14 -12
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -3
- package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +6 -6
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +1 -1
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +7 -7
- package/content/guidance/shared/AGENTS.md +8 -0
- package/content/scripts/README.md +5 -2
- package/content/scripts/check-branch-currency.mjs +11 -0
- package/content/scripts/check-prose.mjs +171 -0
- package/content/scripts/describe-change.mjs +97 -97
- package/content/scripts/manage-jira-ticket.mjs +99 -94
- package/content/scripts/resolve-frontmatter.sh +1 -1
- package/content/scripts/resolve-review-run.mjs +9 -9
- package/content/scripts/select-lede-exemplars.mjs +87 -87
- package/content/scripts/validate-preferences.mjs +146 -0
- package/content/skills/_data/artifact-conventions.md +46 -14
- package/content/skills/_data/branch-currency.md +36 -0
- package/content/skills/_data/change-record.md +2 -2
- package/content/skills/_data/design-priorities.md +3 -3
- package/content/skills/_data/project-stage.md +32 -0
- package/content/skills/_data/recommendation-gradient.md +9 -7
- package/content/skills/_data/scope-and-deferral.md +1 -1
- package/content/skills/_data/spike-conventions.md +1 -1
- package/content/skills/_data/ticket-evaluation.md +2 -2
- package/content/skills/_data/ticket-source-resolution.md +36 -3
- package/content/skills/_data/title-templates.md +19 -11
- package/content/skills/_partials/action-items.md +2 -2
- package/content/skills/_partials/commit-title-rendering.md +1 -1
- package/content/skills/_partials/jira-task-list-flattening.md +1 -0
- package/content/skills/_partials/next-steps-after-plan.md +10 -10
- package/content/skills/_partials/next-steps-after-review.md +9 -9
- package/content/skills/_partials/option-format.md +18 -17
- package/content/skills/_partials/plan-template.md +5 -5
- package/content/skills/_partials/split-ticket-compose.md +1 -1
- package/content/skills/_partials/split-ticket-create.md +1 -1
- package/content/skills/_partials/ticket-and-plan-completeness.md +2 -2
- package/content/skills/_partials/ticket-criteria-conventions.md +3 -3
- package/content/skills/add-change-record/SKILL.md +2 -2
- package/content/skills/align-ticket-with-implementation/SKILL.md +2 -2
- package/content/skills/anti-patterns/SKILL.md +1 -1
- package/content/skills/assess-usability/SKILL.md +96 -0
- package/content/skills/capture-event/SKILL.md +2 -2
- package/content/skills/capture-event/capture-event.mjs +89 -89
- package/content/skills/capture-lede-decision/SKILL.md +4 -4
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +98 -98
- package/content/skills/collaborate/SKILL.md +1 -1
- package/content/skills/create-gh-pr/SKILL.md +24 -9
- package/content/skills/create-pr/SKILL.md +5 -5
- package/content/skills/create-ticket/SKILL.md +61 -16
- package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +95 -94
- package/content/skills/design-and-plan/SKILL.md +13 -10
- package/content/skills/groom-backlog/SKILL.md +8 -6
- package/content/skills/groom-backlog/groom-backlog.mjs +64 -62
- package/content/skills/implement-plan/SKILL.md +25 -21
- package/content/skills/index-prototypes/SKILL.md +85 -30
- package/content/skills/index-prototypes/index-prototypes.mjs +76 -16
- package/content/skills/kb-add/SKILL.md +2 -1
- package/content/skills/kb-add/kb-add.mjs +128 -128
- package/content/skills/kb-curate/SKILL.md +9 -7
- package/content/skills/kb-curate/kb-curate.mjs +103 -103
- package/content/skills/kb-edit/SKILL.md +3 -3
- package/content/skills/kb-edit/kb-edit.mjs +94 -94
- package/content/skills/kb-retrieve/kb-retrieve.mjs +78 -77
- package/content/skills/kb-retrieve-events/SKILL.md +1 -1
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +78 -77
- package/content/skills/kb-update-events/SKILL.md +2 -2
- package/content/skills/kb-update-events/kb-update-events.mjs +108 -108
- package/content/skills/merge-bb-pr/SKILL.md +1 -1
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +5 -5
- package/content/skills/merge-pr/SKILL.md +11 -11
- package/content/skills/migrate-feedback-memories/SKILL.md +3 -2
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +76 -76
- package/content/skills/plan/SKILL.md +1 -1
- package/content/skills/prepare-prototype-brief/SKILL.md +66 -14
- package/content/skills/pull-from-backlog/SKILL.md +3 -3
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +83 -82
- package/content/skills/refine-plan/SKILL.md +7 -3
- package/content/skills/refine-prototype/SKILL.md +113 -0
- package/content/skills/respond-to-review/SKILL.md +1 -1
- package/content/skills/review-bb-pr/SKILL.md +1 -1
- package/content/skills/review-branch/SKILL.md +4 -2
- package/content/skills/review-criteria/SKILL.md +36 -3
- package/content/skills/review-gh-pr/select-pr-ticket.mjs +6 -6
- package/content/skills/revise-comments/SKILL.md +38 -5
- package/content/skills/revise-prose/SKILL.md +1 -1
- package/content/skills/revise-prose/revise-prose.mjs +119 -119
- package/content/skills/save-artifact/SKILL.md +2 -0
- package/content/skills/streamline-guidance/SKILL.md +1 -1
- package/content/skills/streamline-guidance/streamline-guidance.mjs +86 -86
- package/content/skills/summarize-change/SKILL.md +22 -13
- package/content/skills/testing-conventions/SKILL.md +74 -7
- package/content/skills/triage-spike-findings/SKILL.md +113 -0
- package/content/skills/triage-spike-findings/triage-spike-findings.mjs +71 -0
- package/content/skills/typescript-testing-conventions/SKILL.md +50 -1
- package/content/skills/update-jira-ticket/SKILL.md +20 -8
- package/content/skills/update-jira-ticket/update-jira-ticket.mjs +7 -7
- package/content/skills/update-project-guidance/SKILL.md +2 -2
- package/content/subagents/_data/claude.yaml +6 -0
- package/content/subagents/_data/rovo.yaml +12 -2
- package/content/subagents/canary.md +2 -1
- package/content/subagents/disposition-challenger.md +78 -0
- package/content/subagents/entry-drafter.md +14 -10
- package/content/subagents/handoff-reviewer.md +2 -2
- package/content/subagents/plan-reviewer.md +1 -1
- package/content/subagents/prose-reviser.md +4 -2
- package/content/subagents/ticket-assessor.md +9 -6
- package/content/subagents/usability-assessor.md +157 -0
- package/package.json +15 -11
- package/schemas/preferences.v1.json +29 -2
- package/schemas/work-types.v1.json +1 -1
- package/content/skills/testing-conventions/mistakes.md +0 -1
package/README.md
CHANGED
|
@@ -5,112 +5,137 @@
|
|
|
5
5
|
The CodeAssembly library of agent guidance: rulebooks, skills, and subagents for coding harnesses, which the [`codeassembly`](../agents/README.md) CLI deploys into Claude Code and Rovo Dev.
|
|
6
6
|
|
|
7
7
|
<!-- section:release-notes -->
|
|
8
|
-
## Release notes — v0.
|
|
8
|
+
## Release notes — v0.2.0 (2026-10-23)
|
|
9
9
|
|
|
10
10
|
### 🎉 Features
|
|
11
11
|
|
|
12
|
-
-
|
|
13
|
-
- Adds
|
|
14
|
-
-
|
|
15
|
-
- Adds a
|
|
16
|
-
-
|
|
17
|
-
-
|
|
18
|
-
-
|
|
19
|
-
- Adds
|
|
20
|
-
-
|
|
21
|
-
- Adds
|
|
22
|
-
- Adds the
|
|
23
|
-
- Adds
|
|
24
|
-
-
|
|
25
|
-
-
|
|
26
|
-
-
|
|
27
|
-
-
|
|
28
|
-
- Adds
|
|
29
|
-
- Adds the `
|
|
30
|
-
- Adds the `
|
|
31
|
-
-
|
|
32
|
-
-
|
|
33
|
-
-
|
|
34
|
-
-
|
|
35
|
-
-
|
|
36
|
-
- Adds
|
|
37
|
-
-
|
|
38
|
-
-
|
|
39
|
-
-
|
|
40
|
-
-
|
|
41
|
-
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
-
|
|
46
|
-
-
|
|
47
|
-
- Adds a
|
|
48
|
-
-
|
|
49
|
-
-
|
|
50
|
-
-
|
|
51
|
-
-
|
|
52
|
-
- Adds a
|
|
53
|
-
-
|
|
54
|
-
-
|
|
55
|
-
-
|
|
56
|
-
- Adds the `
|
|
57
|
-
-
|
|
58
|
-
- Adds
|
|
59
|
-
- Adds
|
|
60
|
-
-
|
|
61
|
-
-
|
|
62
|
-
- Adds a
|
|
63
|
-
-
|
|
64
|
-
- Adds a "
|
|
65
|
-
-
|
|
66
|
-
-
|
|
67
|
-
-
|
|
68
|
-
-
|
|
69
|
-
-
|
|
70
|
-
-
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
-
|
|
75
|
-
-
|
|
76
|
-
-
|
|
77
|
-
-
|
|
12
|
+
- Replaces the list of ideas to adopt in the `comparison` artifact written by `prepare-prototype-brief` with an idea table that lists every distinctive idea of the round, those of rejected and losing prototypes included, with the prototypes that have it and the requirement that it answers. (#2027)
|
|
13
|
+
- Adds a step to `prepare-prototype-brief`, reached also from the verdict read-back of `index-prototypes`, which takes the developer through a keep, adapt, defer, or drop decision on each row of the idea table, accepts new ideas that the developer states while judging, and saves the result as a ticket-level `idea-decisions` artifact. (#2027)
|
|
14
|
+
- Requires, in the product-development stages of the `williamthorsen-workflow-preferences` rulebook, a decision on every prototype idea before the end vision, which cites the `idea-decisions` artifact, and a record of each decision in the design doc. (#2027)
|
|
15
|
+
- Adds a `number` to each `index-prototypes` manifest entry, assigned at a slug's first registration and kept by its later versions, and leads each index card title and the winner summary with it, as in "3. Catalog first". (#2030)
|
|
16
|
+
- Numbers a manifest written before this change in order of each slug's first registration when it is read, and writes those numbers to it at the next registration. (#2030)
|
|
17
|
+
- Updates `index-prototypes` and `prepare-prototype-brief` to name each prototype to the developer as `{number}. {title}` in reports, the comparison, the idea table, and the idea decisions, and to accept a bare number as a reference to a prototype, asking when no prototype has that number. (#2030)
|
|
18
|
+
- Adds the `ui-copy-conventions` rulebook, delivered as the `consult-ui-copy-conventions` skill, which sets rules for labels, buttons, helper text, errors, register, and case, and a copy budget for each page, and which defers to a project's own content guidelines where the two conflict. (#2032)
|
|
19
|
+
- Adds `ui-copy-conventions` to the `recommended` collection, and directs plans to name its copy rules and copy budget in the key decisions of any task that writes interface text or builds a page, a prototype, or a UI component. (#2032)
|
|
20
|
+
- Changes `prepare-prototype-brief` to forbid builders from quoting the brief into the page, to require the demo chrome inside an element marked `data-demo`, and to judge each prototype's product copy against `ui-copy-conventions`. (#2032)
|
|
21
|
+
- Adds the `copy-probe` command to the `index-prototypes` helper, which prints a function for the Playwright MCP's `browser_evaluate` that lists a page's strings of four or more words and skips everything inside `data-demo`. (#2032)
|
|
22
|
+
- Adds the `index-prototypes describe-set` command, which reads a set summary (`shared`, `changes`, `try`) from a JSON file into the manifest; the index page shows that summary below its title, with `try` as a numbered list. (#2034)
|
|
23
|
+
- Adds a repeatable `--note "<label>: <value>"` flag to `index-prototypes register`, which stores each note on the prototype's entry and shows the notes on its card as a definition list in the order given. (#2034)
|
|
24
|
+
- Directs the agent in the `index-prototypes` and `prepare-prototype-brief` skills to choose one list of note labels for the set, to collect a value for each label from every builder, and to write the set summary in a new "Describe the set" step each round. (#2034)
|
|
25
|
+
- Adds drafted titles to `groom-backlog`, which shows a replacement title from the `ticket-assessor` subagent in the digest, applies it with `gh issue edit --title`, and lists "Title" among the parts that the ticket comment reports as revised. (#2038)
|
|
26
|
+
- Adds the `project.maturity` (`hobby`, `early`, `production`), `project.sensitivity` (`low`, `personal`, `confidential`), and `project.audience` (`owner`, `team`, `public`) keys to `.agents/preferences.yaml`, which `derive-session-context` reports as `project_maturity`, `project_sensitivity`, and `project_audience`, or as `null` for a key that the project file does not declare. (#2044)
|
|
27
|
+
- Directs `design-and-plan` and `plan` to treat the declared project stage as the premise of every security, availability, and infrastructure decision, to add machinery beyond that stage only for a named asset or need, and to ask for each undeclared value and then declare it in the project's preferences file. (#2044)
|
|
28
|
+
- Adds the project's declared stage to the design-doc contents that the `williamthorsen-workflow-preferences` rulebook lists for a product's end vision. (#2044)
|
|
29
|
+
- Adds the `check-preferences.mjs` script, which validates a preferences file against the bundled schema, prints its findings as JSON, and exits 1 on an invalid value or a missing required key, reporting an unrecognized key as a warning that names the nearest known key. (#2044)
|
|
30
|
+
- Adds the `refine-prototype` skill, which applies the developer's commands to one prototype page with the development gates off, carries the round's kept and adapted ideas onto it, snapshots each accepted version into the ticket's prototype set, and records every accepted change in a `refinement-log` artifact that the end vision reads. (#2040)
|
|
31
|
+
- Gives each prototype version an id, `{number}.{version}`, that leads the index card and the first line of the page's `data-demo` band, with a `resolve-ids` command on the `index-prototypes` helper that resolves the ids before the prototypes are built and a `--number` flag on `register` that refuses a registration whose number disagrees with the manifest. (#2040)
|
|
32
|
+
- Adds the `assess-usability` skill, available on the Claude harness only, which dispatches a `usability-assessor` subagent for each of three to five lenses in turn and merges their reports into a `usability-findings` artifact that ranks the findings by effect and reach and that `triage-spike-findings` takes as input. (#2045)
|
|
33
|
+
- Adds the `triage-spike-findings` skill, which grades the confidence and value of every item that a findings artifact leaves undisposed, has the new `disposition-challenger` subagent argue against each grade, and then creates the `confidence:`- and `value:`-labelled child tickets under an umbrella ticket and posts every disposition on the triage ticket, on GitHub repositories that have both label families. (#2049)
|
|
34
|
+
- Adds a `--label` argument to `create-ticket`, which applies the given labels on GitHub in addition to the resolved scope and type labels and reports them as skipped on Jira. (#2049)
|
|
35
|
+
- Stops `create-ticket` from asking for confirmation of a relationship supplied through `--parent`, `--blocked-by`, or `--blocking`, and lists that relationship in the completion output. (#2049)
|
|
36
|
+
- Adds the `check-site --target <url-or-host>` subcommand to `manage-jira-ticket.mjs`, which prints `acli`'s active site and the ticket's site as JSON and, when they differ, exits non-zero and names the `acli jira auth switch` command that makes the ticket's site active. (#2052)
|
|
37
|
+
- Adds the `jira-clients` guidance hook to `update-jira-ticket`, through which a machine adds its own Jira client, with the sites that it reaches and its rank, to the clients that the Jira skills read and create through. (#2052)
|
|
38
|
+
- Adds an "External programs" section to the `testing-conventions` skill, which directs that code reach git or another external program through an adapter received as a dependency, that tests of that code pass a fake adapter, and that only the adapter's own test run the real program. (#2055)
|
|
39
|
+
- Adds an "External programs" section to the `typescript-testing-conventions` skill, with an example of an adapter type, a real adapter used as a parameter default, and a test that passes an object literal as the fake, and states a preference for that parameter over `vi.mock`. (#2055)
|
|
40
|
+
- Rewrites the description of the `testing-conventions` skill to name how a test reaches git and other external programs, and to direct agents to consult the skill before writing or changing a test. (#2055)
|
|
41
|
+
- Move kb's git calls behind an injectable adapter (#2077)
|
|
42
|
+
|
|
43
|
+
Adds an optional `git` parameter to `check`, `enumerateNotes`, and `enumerateNotePaths` in `@williamthorsen/kb/check`, which takes a `KbGit` adapter so that a consumer's tests can run these functions without a real git repository. The change also routes every git call inside kb through one such adapter and replaces the repositories that kb's tests built with a fake adapter.
|
|
44
|
+
|
|
45
|
+
- Changes the next-steps menus of the planning, implementation, and review skills to name each skill in the harness's own invocation syntax, such as `/refine-plan` on Claude Code and `!refine-plan` on Rovo, so that a user can paste an option line without retyping it. (#2084)
|
|
46
|
+
- Adds a "Where a test goes" section to the `testing-conventions` skill, which directs each case to the cheapest tier that can observe it, limits an expensive tier (one that spawns a process, starts a runtime, or builds a full fixture) to one smoke example per entry or verb, and requires a change to delete the higher-tier examples that its cheaper coverage supersedes and to justify each expensive-tier example that it adds. (#2086)
|
|
47
|
+
- Adds a "Test placement" section to the `review-criteria` skill, which classes as a Warning an added expensive-tier example that a cheaper tier could observe, and also a higher-tier suite that the change superseded but kept. (#2086)
|
|
48
|
+
- Changes the test criterion in `ticket-criteria-conventions` and `plan-template` to ask for coverage at the cheapest tier that observes the behavior, rather than for coverage by tests alone. (#2086)
|
|
49
|
+
- Changes the `accessibility-conventions` and `shared-data-conventions` rulebooks to `skill` delivery alone, so that they no longer appear in every session's guidance file and are reached through `consult-accessibility-conventions` and `consult-shared-data-conventions`, and adds an "Interfaces" criterion to `review-criteria` that points a review of colour tokens, text styles, pages, or UI components to `accessibility-conventions`. (#2087)
|
|
50
|
+
- Adds an "Always-loaded context" section to `review-criteria`, which classifies a change as a Warning when it makes a rulebook ambient or grows an `AGENTS.md`, a `CLAUDE.md`, or another file loaded at session start, unless nearly every session needs the content. (#2087)
|
|
51
|
+
- Updates `codeassembly-content-specification` to version 30, which states that `delivery` is required and that `ambient` fits only content that nearly every session needs. (#2087)
|
|
52
|
+
- Adds a rule to `prepare-prototype-brief` that directs the brief's author to describe an audience-facing view by what the audience sees, and adds a line to the brief check that has the author rewrite phrases such as "mystery" and "unknown to" without the withheld information. (#2089)
|
|
53
|
+
- Makes `create-gh-pr` assign each pull request that it creates to the authenticated `gh` user, record the applied assignee in the `pull-request` artifact, and report the assignee as skipped when GitHub does not apply it. (#2090)
|
|
54
|
+
- Adds setup rules to the `testing-conventions` skill that count a database engine as an expensive tier, call for the cheapest setup that fits the time budget, keep setup cost independent of the number of test files, and reject a raised hook timeout as a fix. (#2092)
|
|
55
|
+
- Adds a "Code that uses a database" section to the `testing-conventions` skill, which limits database tests to code whose subject is SQL, directs logic that only passes through SQL to a fake client or a mocked module boundary, and rules out a test per constraint. (#2092)
|
|
56
|
+
- Adds four Warnings to the `review-criteria` skill for database and setup defects in tests that the change adds, splits, or modifies, and changes the split that it proposes for a grown test file to share the file's expensive setup first. (#2092)
|
|
57
|
+
- Adds the `cli-conventions` rulebook, delivered as the `consult-cli-conventions` skill, which states that a CLI printing a doc as a help topic renders a link to another topic as the `<bin> help <topic>` command, renders any other link as its absolute URL, and accepts the doc's file stem as a name for the topic. (#2093)
|
|
58
|
+
- Adds `cli-conventions` to the `recommended` collection, so that a project declaring that collection receives the rulebook. (#2093)
|
|
59
|
+
- Adds `--repo OWNER/REPO` to `/create-ticket`, which files the ticket in that GitHub repository and resolves its title format, reference prefix, scope, and labels from the configuration on that repository's default branch. (#2094)
|
|
60
|
+
- Adds `--project-root <dir>` to `describe-change render-titles` and `resolve-labels`, which then read `.agents/preferences.yaml` and `.meta/label-map.json` from that directory in place of the invoking repository's root. (#2094)
|
|
61
|
+
- Makes `describe-change resolve-labels` warn on stderr about each type or scope that a configured label map does not define, where it previously omitted the label without a message. (#2094)
|
|
62
|
+
- Adds a `medium` input to `assess-usability`. When set to `cli`, each `usability-assessor` lens runs the built binary in its own scratch git repository and saves text transcripts as evidence, and the styling-and-access lens is replaced by an output-and-access lens that checks `NO_COLOR`, piped output, 80-column width, and help and error text. (#2095)
|
|
63
|
+
- Orders the `ticket` items of `triage-spike-findings` by value, then confidence, with record order breaking ties, when the skill creates the child tickets and when it lists them in the checkpoint table, the dispositions comment, and the report, so that the children's issue numbers follow that order. (#2096)
|
|
64
|
+
- Adds a rule to the "Technical recommendations" guidance that directs an agent to name the best-practice solutions to a design problem and the conditions under which each one fits before it weighs options, to label an option that departs from all of them as non-standard with the reason that none fits, and to recommend revising an existing API rather than an addition that works around its contract. (#2098)
|
|
65
|
+
- Includes the "Technical recommendations" guidance in the `ticket-assessor` subagent, which validates a ticket's proposed approach. (#2098)
|
|
66
|
+
- Extends the `cli-conventions` rulebook from help topics to the whole interface of a command-line tool in any language, adding rules for `--help` on every command and subcommand, an exit-code table, error messages that name the fix, and step and outcome reports for commands that change state. (#2099)
|
|
67
|
+
- Reduces the `shell-conventions` rulebook to how a bash script implements the `cli-conventions` rules, and changes its `show_usage` template to write requested help to stdout and to exit 2 on an unknown command. (#2099)
|
|
68
|
+
- Adds a "DOM environment" section to the `typescript-testing-conventions` skill, which directs a TypeScript test that renders into a DOM to run under happy-dom and allows jsdom only at an opt-in whose comment names the behavior that happy-dom lacks. (#2101)
|
|
69
|
+
- Adds the `codeassembly-validate-preferences` bin to `codeassembly-guidance`, which validates each named preferences file against the bundled schema without network access, reports a missing or unparsable file as an error, prints text or one JSON object per file under `--json`, and treats warnings such as an unrecognized key as failures under `--strict`. (#2103)
|
|
70
|
+
- Renames the deployed `check-preferences.mjs` helper to `validate-preferences.mjs` and gives it the bin's behavior: several files per run, text output by default, and the `--json`, `--strict`, and `--help` options. (#2103)
|
|
71
|
+
- Directs the agent, in the `williamthorsen-collaboration-preferences` rulebook and the option-format rule, to start each line that states a decision awaiting the checkpoint with ⏳, in a turn's narrative as well as in the plan and spike templates' `## Decisions taken` section, where the marker replaces the `(provisional)` parenthetical. (#2104)
|
|
72
|
+
- Extends `triage-spike-findings` to have the agent decide the blockers of each ticket that it creates, create every blocker before the tickets that it blocks, link them through `create-ticket --blocked-by`, and list them in a "Blocked by" column of the dispositions comment. (#2105)
|
|
73
|
+
- Adds to `williamthorsen-ticketing-preferences` a rule to record a blocker whenever there is some probability that one ticket affects another and should land first, including when one ticket's design takes another ticket's outcome as an input. (#2105)
|
|
74
|
+
- Adds a directive to the "Handoffs" section of `williamthorsen-collaboration-preferences` that tells the agent to hand over a check of more than one command as one paste-ready script, which cleans up after itself and prints only the facts that the agent needs, and to confirm which machine its commands run on, such as by comparing `hostname`, before it runs or hands over a check of a GUI application. (#2106)
|
|
75
|
+
- Adds to `accessibility-conventions` the states that every clickable element shows (a pointer cursor, a hover change, and a focus indicator that meets 3:1 non-text contrast), and requires a browser check of each change to a visible component, with a report that the check did not run when a browser is unavailable. (#2109)
|
|
76
|
+
- Directs `implement-plan` to run that browser check for any change to a visible component, whether or not the plan lists it, and to report what the check found, and adds the interaction states and the check to the plan template's interface guidance. (#2109)
|
|
77
|
+
- Directs `review-criteria` to check each new or changed interactive element in a browser rather than by reading the diff alone, and adds the outcome of that check to the technical assessment in both `review-branch` report templates. (#2109)
|
|
78
|
+
- Makes `design-and-plan`, `plan`, and `refine-plan` report each open blocker of the resolved GitHub or Jira ticket by reference and title, and then continue. (#2113)
|
|
79
|
+
- Makes `implement-plan` ask the user to confirm before it starts the first task when the governing ticket has an open blocker. (#2113)
|
|
80
|
+
- Extends the blocker check to a ticket artifact, which the skills check against the remote ticket named by its `ticket_ref` frontmatter. (#2113)
|
|
81
|
+
- Lets `refine-plan` resolve a Jira ticket by URL or key through the Jira clients that the ticket source resolution ranks, where it previously fetched a Jira URL as a web page. (#2113)
|
|
82
|
+
- Adds a rule to `williamthorsen-tooling-preferences` that directs an agent to log into a local instance of the app under work without asking the developer, and to set a development credential in an untracked local config file when the app needs one, which the rulebook does not count as minting a credential. (#2115)
|
|
83
|
+
- Limits the login that the handoff ladder in `williamthorsen-collaboration-preferences` names among the resources that an agent asks the developer to supply to a login to a remote service, which excludes an app's local development login. (#2115)
|
|
84
|
+
- Adds a step to `design-and-plan`, `plan`, `refine-plan`, and `implement-plan` that checks the branch against the remote's default branch before the work starts, fast-forwarding a branch that lacks commits and uncommitted changes of its own and otherwise listing the gained commits and asking whether to bring them in. (#2119)
|
|
85
|
+
- Adds the `check-branch-currency.mjs` script, which fetches the remote's default branch and reports as JSON how far the checked-out branch is behind and ahead of it, whether its tree is clean, and which gained commits touch the paths passed with `--path`. (#2119)
|
|
86
|
+
- Adds an "Authorship" section to the shared `AGENTS.md`, which states that a creator, reporter, or author field shows the account that made an item rather than who wrote it, and forbids inferring from that field that the developer wrote the item. (#2120)
|
|
87
|
+
- Changes `ticket-evaluation.md` to tell the agent to treat a ticket's content as unsourced, whichever account created the ticket, until the agent traces the content to a source. (#2120)
|
|
88
|
+
- Adds a "Subcommand names" section to the `cli-conventions` rulebook, which requires a subcommand that acts to name its action and its object, prescribes a flat verb-object name such as `show-instance-page` while the object has one action and a noun group such as `instance-page show` once it has several, and rejects an existing name that breaks these rules as precedent. (#2121)
|
|
89
|
+
- Makes `kb-curate` report `missing-destination` when `--kb` is absent and no `.kb/` is discoverable, and `no-default` when `--kb @default` is given without a configured `default_kb`, where both cases previously returned `no-kb-resolvable`. (#2122)
|
|
90
|
+
- Makes `kb-edit` report a note outside any discoverable `.kb/` as `missing-destination` instead of `no-kb-resolvable`, the code that `kb-add` uses for the same condition. (#2122)
|
|
91
|
+
- Rewrites the `.editorconfig` bullet in the shared "Style" guidance to direct agents to follow `.editorconfig` and to fill new comments to the `max_line_length` that it sets. (#2123)
|
|
92
|
+
- Adds rules to `cli-conventions`, each with an example, on when a behavior is a subcommand rather than an option, standard option names such as `--config`, `--dry-run`, and `--write`, the order in which settings resolve, which commands write by default, `--json` output, color, error messages that suggest the nearest valid name and never take a secret as an argument, and keeping a command's logic apart from its presentation. (#2134)
|
|
93
|
+
- Changes the exit code that `cli-conventions` assigns to a usage error, such as bad input or an unknown command or option, from 1 to 2, and adds exit code 1 for a check that ran and found problems. (#2134)
|
|
94
|
+
- Changes the default exit code of the `show_usage` template in `shell-conventions` from 1 to 2, so that a bare `show_usage` call covers every usage error, including an unknown command. (#2134)
|
|
95
|
+
- Makes `select-lede-exemplars.mjs` act on the breaking marker, which it previously discarded: An unmarked request no longer returns a breaking record, and a request marked by a `!` on `--type` returns breaking records before non-breaking ones within each widening step. (#2136)
|
|
96
|
+
- Adds a `--breaking` flag to `select-lede-exemplars.mjs`, which marks a `--type` or `--tier` request as breaking, and adds a `breaking` field to the JSON output, which reports whether the request was marked. (#2136)
|
|
97
|
+
- Changes the `entry-drafter` subagent to request exemplars once per pair of work type and breaking marker, passing `--breaking` for a breaking entry, rather than once per work type. (#2136)
|
|
98
|
+
- Defines the members of the `triage` collection with `'@unclaimed'`, so that `codeassembly` deploys a newly added library artifact through `triage` until the artifact is promoted to another collection or declares `standalone:`. (#2137)
|
|
99
|
+
- Adds the `overused-word` rule to the `revise-prose` sweep, which reports one candidate per sentence that contains a word from the plain-speech calibration's "Words to look for" list or an inflection of one, lists the matched words, and leaves `prose-reviser` to repair the site or reject a use in a sense that the list keeps. (#2139)
|
|
100
|
+
- Adds the `check-prose.mjs` script, which runs every `revise-prose` detector over one Markdown file at any path without reading or writing the sweep record, and exits 1 when it reports candidates and 2 when it cannot read the file. (#2141)
|
|
101
|
+
- Adds a writing-rules check to step 6 of `summarize-change`, which runs `check-prose.mjs` over the lede, each entry's `text` and `migration`, and the "Why" section, and directs the session to redispatch the `entry-drafter` with the new `writing-rule` rejection code for a confirmed violation in a drafted passage. (#2141)
|
|
102
|
+
- Extends `revise-comments` to add a missing description to each function, method, class, and component, test helpers included, and to rewrite a description that misstates its code, with an instruction to ask the user first when the code rather than the description could be wrong. (#2146)
|
|
103
|
+
- Adds a "Test data" section to the `testing-conventions` skill, which requires each test to use the smallest data that proves its behavior and requires code that reads data from a module-level singleton to take it as a parameter or from a context whose default is the real value. (#2167)
|
|
104
|
+
- Extends the "Fix the design, not the timeout" rule in `testing-conventions` from a hook's timeout to a test's and a tier's timeout, set in a test or in config, and permits a raise only when smaller data, injection, and shared setup do not apply and the plan or the pull-request description states why. (#2167)
|
|
105
|
+
- Adds a Warning to `review-criteria` for a raised hook, test, or tier timeout, which a stated reason does not exempt, and a Warning for a test that renders or builds production-scale data, replacing the narrower "A raised hook timeout" item. (#2167)
|
|
78
106
|
|
|
79
107
|
### 🐛 Bug fixes
|
|
80
108
|
|
|
81
|
-
- Fixes the issue that
|
|
82
|
-
-
|
|
83
|
-
- Fixes the issue that `
|
|
84
|
-
- Fixes the issue that `
|
|
85
|
-
- Fixes the issue that `
|
|
86
|
-
- Fixes the issue that
|
|
87
|
-
- Fixes the issue that `
|
|
88
|
-
- Fixes the issue that
|
|
89
|
-
- Fixes the issue that `
|
|
90
|
-
- Fixes the issue that `
|
|
91
|
-
- Fixes the issue that
|
|
92
|
-
-
|
|
93
|
-
- Fixes the issue that
|
|
94
|
-
- Fixes the issue that `
|
|
95
|
-
- Fixes the issue that `
|
|
96
|
-
-
|
|
97
|
-
- Fixes the issue that `
|
|
98
|
-
- Fixes the issue that
|
|
99
|
-
- Fixes the issue that `
|
|
100
|
-
- Fixes the issue that `
|
|
101
|
-
- Fixes the issue that
|
|
102
|
-
- Fixes the issue that `entry-drafter` and `title-voice.md` stated their doctrine in figures forbidden by the plain-speech rule, such as "earns its place", "the count is the tell", and "a ceiling, not a target", by replacing each with a literal statement. (#2005)
|
|
103
|
-
- Fixes the issue that `prepare-prototype-brief` stated its instructions as aphorisms and agentless statements, such as "Settled intent stays settled", rather than as imperatives that name the action. (#2018)
|
|
104
|
-
- Fixes the issue that `entry-drafter` and `summarize-change` stated that the lede reaches the changelog and the release notes, which `release-kit` renders from the change entries without the lede. (#2023)
|
|
109
|
+
- Fixes the issue that `summarize-change` reported a branch's own steps and a ticket's backstory as what the change did, by having the `entry-drafter` subagent and the summary's audit accept only the diff against the default branch as evidence of what changed. (#2029)
|
|
110
|
+
- Fixes the issue that the `## Why` section of a `summarize-change` summary retold how the need for a change arose, by defining that section as the purpose that the change serves. (#2029)
|
|
111
|
+
- Fixes the issue that `entry-drafter` wrote where code or values were copied from, or why the work is split across pull requests, into the lede and the entries, including when a ticket's `## Problem` section stated it. (#2031)
|
|
112
|
+
- Fixes the issue that `summarize-change` accepted how the work is staged across pull requests as the purpose stated in a change summary's `## Why` section. (#2031)
|
|
113
|
+
- Fixes the issue that `groom-backlog collect` selected a ticket again when its only update was the decision that the sweep itself had applied, because GitHub records that update a moment after the sweep's comment. (#2038)
|
|
114
|
+
- Fixes the issue that `create-ticket` and `design-and-plan`'s Jira write did not direct the agent to flatten task-list syntax before submitting through a Markdown or HTML Jira client, which Jira stores as bullets reading `\[ \]`, on any deployment without `update-jira-ticket`. (#2050)
|
|
115
|
+
- Fixes the issue that `manage-jira-ticket.mjs create` created a Jira work item on `acli`'s active site when that site differed from the host of `ticket.base_url`, and makes it exit with the fallback `wrong-site` or `site-unreadable` without writing to Jira, reading `ticket.base_url` from the repository's preferences or the global file. (#2052)
|
|
116
|
+
- Fixes the issue that ticket resolution, `update-jira-ticket`, and `create-ticket` reported a Jira ticket on another site as missing, by directing each to run `manage-jira-ticket.mjs check-site` before calling `acli` and to report the wrong site and the `acli jira auth switch` command instead. (#2052)
|
|
117
|
+
- Fixes the issue that the `live-worktree-policy` rulebook named the removed `list-repos --tag live` command for listing the repos tagged `live`, and replaces it with `thor-repo list --tag live`. (#2053)
|
|
118
|
+
- Fixes the issue that a `summarize-change` redispatch did not send `entry-drafter` the type corrected by the audit, which left the drafter to rewrite the entry in the form of the old type. (#2058)
|
|
119
|
+
- Fixes the issue that the artifact guidance never stated what the artifact directory is for, by stating that it is the developer's audit trail rather than a source of truth, directing durable instructions to the repository or to a skill or rulebook, and telling the agent to verify what a search of artifacts returns against the repository, the tickets, and the pull requests. (#2070)
|
|
120
|
+
- Fixes the issue that `williamthorsen-workflow-preferences` did not say that the branch and worktree for a ticket's work are settled, which left agents asking the developer which one to use. (#2082)
|
|
121
|
+
- Fixes the issue that `design-and-plan` ended a session that split a ticket without a launch prompt for each resulting ticket, and that its `Next action` menu could offer to implement an umbrella's child in the umbrella's worktree. (#2083)
|
|
122
|
+
- Fixes the issue that the `triage-spike-findings` helper's `check-labels` command crashed with "e is not a function" instead of running `gh label list`, which stopped the skill before triage began. (#2085)
|
|
123
|
+
- Fixes the issue that `williamthorsen-collaboration-preferences` and the `action-items` and `option-format` partials stated many directives in the indicative, which hid whether the agent was to act, by restating them as imperatives addressed to the agent. (#2106)
|
|
124
|
+
- Documents in the `kb-add` skill the `readonly-kb` error code, which its helper already returned, and tells the agent to have the user choose a writable KB. (#2122)
|
|
125
|
+
- Fixes the issue that the rulebooks, skills, subagents, and partials in `codeassembly-guidance` contained sentences that the library's own current writing rules flag, such as figurative verbs, "no" used as a determiner, and reduced object relatives, and keeps each rulebook's `version` because the repairs do not change what it asks. (#2130)
|
|
126
|
+
- Fixes the issue that messages printed by `describe-change`, `index-prototypes`, `resolve-review-run`, `revise-prose`, and `triage-spike-findings` broke the writing rules, for example by saying `no manifest in` a directory rather than that the directory does not contain a manifest, and keeps each message's error code. (#2132)
|
|
127
|
+
- Fixes the issue that the artifact conventions told agents to run `export-ai-artifacts.sh`, which has been deleted, and called a git-ignored `base_dir` the default when the documented default is `~/ai-artifacts`. (#2135)
|
|
128
|
+
- Fixes the issue that `revise-prose` reported a file as swept after its prose was edited, by recording a hash of each file's extracted prose in `.agents/revise-prose.yaml` and reporting the file as unswept when the current hash differs. (#2143)
|
|
129
|
+
- Fixes the issue that the leader check in the option-format contract and the `williamthorsen-collaboration-preferences` rulebook did not cover gated decisions, and adds a first step that searches each alternative for a disqualifying cost, including one that follows from the work's constraints and acceptance criteria. (#2145)
|
|
105
130
|
|
|
106
131
|
### ⚡ Performance
|
|
107
132
|
|
|
108
|
-
-
|
|
133
|
+
- Shortens the `index-prototypes` skill by 675 bytes, cutting explanations that a neighboring sentence restated, and leaves its behavior unchanged. (#2040)
|
|
109
134
|
<!-- /section:release-notes -->
|
|
110
135
|
|
|
111
136
|
## Using the library
|
|
112
137
|
|
|
113
|
-
A declaration names the library as a source and
|
|
138
|
+
A declaration names the library as a source and selects artifacts from it, usually through a collection. For the home harness directories, clone the repository and declare its content directory in `~/.agents/codeassembly.yaml`:
|
|
114
139
|
|
|
115
140
|
```yaml
|
|
116
141
|
sources:
|
|
@@ -142,7 +167,7 @@ The `codeassembly-content-specification` rulebook ([`content/guidance/rulebooks/
|
|
|
142
167
|
|
|
143
168
|
A skill that needs more than a few lines of shell runs a TypeScript helper. Its source lives under `src/`, `content/codeassembly-content.yaml` declares it, and `codeassembly bundle-helpers` builds it into a tracked `.mjs` bundle beside the skill. Commit a helper's source change together with its rebuilt bundle.
|
|
144
169
|
|
|
145
|
-
The package's `check` runs the tests, then `codeassembly validate` and `codeassembly bundle-helpers --check`, which fail on content that would
|
|
170
|
+
The package's `check` runs the tests, then `codeassembly validate` and `codeassembly bundle-helpers --check`, which fail on content that would be deployed to a consumer broken and on a bundle that is stale.
|
|
146
171
|
|
|
147
172
|
## Preferences
|
|
148
173
|
|
|
@@ -154,7 +179,11 @@ Agent behavior is configured through `.agents/preferences.yaml` files. The resol
|
|
|
154
179
|
|
|
155
180
|
Project-level values take precedence over global. An explicitly empty value at the project level (e.g., `title_format: ''`) overrides a non-empty global value.
|
|
156
181
|
|
|
157
|
-
The package publishes a JSON Schema for the file; [Schemas](docs/schemas.md) gives its identifier and versioning.
|
|
182
|
+
The package publishes a JSON Schema for the file; [Schemas](docs/schemas.md) gives its identifier and versioning. To validate preferences files in a repository's own checks, install this package and run its bin on them; [Validation](docs/preferences.md#validation) states its options and rules.
|
|
183
|
+
|
|
184
|
+
```sh
|
|
185
|
+
codeassembly-validate-preferences --strict .agents/preferences.yaml
|
|
186
|
+
```
|
|
158
187
|
|
|
159
188
|
## Helper reference
|
|
160
189
|
|
|
@@ -163,3 +192,4 @@ The package publishes a JSON Schema for the file; [Schemas](docs/schemas.md) giv
|
|
|
163
192
|
- [Next-ticket helper](docs/pull-from-backlog-helper.md): the helper that the `pull-from-backlog` skill runs.
|
|
164
193
|
- [Prototype index helper](docs/index-prototypes-helper.md): the helper that the `index-prototypes` skill runs.
|
|
165
194
|
- [Guidance streamlining helper](docs/streamline-guidance-helper.md): the helper that the `streamline-guidance` skill runs.
|
|
195
|
+
- [Findings triage helper](docs/triage-spike-findings-helper.md): the helper that the `triage-spike-findings` skill runs.
|
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
// Runs the bundled validate-preferences helper. The bundle is self-contained, so the package doesn't need any runtime
|
|
4
|
+
// dependencies, and its own entry guard stays false here because `process.argv[1]` names this file.
|
|
5
|
+
import path from 'node:path';
|
|
6
|
+
import process from 'node:process';
|
|
7
|
+
|
|
8
|
+
import { runValidatePreferences } from '../content/scripts/validate-preferences.mjs';
|
|
9
|
+
|
|
10
|
+
const programName = path.basename(process.argv[1] ?? 'codeassembly-validate-preferences', '.js');
|
|
11
|
+
|
|
12
|
+
try {
|
|
13
|
+
process.exitCode = await runValidatePreferences(process.argv.slice(2), process.cwd(), programName);
|
|
14
|
+
} catch (error) {
|
|
15
|
+
const message = error instanceof Error ? error.message : String(error);
|
|
16
|
+
process.stderr.write(`${programName}: ${message}\n`);
|
|
17
|
+
process.exitCode = 1;
|
|
18
|
+
}
|
|
@@ -61,13 +61,13 @@ A **relative Markdown link** cannot serve both a skill host and a rulebook host.
|
|
|
61
61
|
|
|
62
62
|
A partial that `guidance/shared/AGENTS.md` inlines does not contain any relative link at all. That file is inlined into each harness's guidance file at the harness home root, where a source-tree-relative target names nothing, so the template-variable form is the only one that resolves to a file from there. `codeassembly validate` scans the expanded body and reports a relative target that it finds.
|
|
63
63
|
|
|
64
|
-
A **`{rulebook:<slug>}` token** cannot serve both a skill body and a support entry under `skills/`. The deployed rulebook set is available only to a host that resolves a declaration, and a source's support entries
|
|
64
|
+
A **`{rulebook:<slug>}` token** cannot serve both a skill body and a support entry under `skills/`. The deployed rulebook set is available only to a host that resolves a declaration, and a source's support entries are delivered to every consumer of the source, whichever rulebooks that consumer declares. The token renders in the skill but breaks the support entry's delivery.
|
|
65
65
|
|
|
66
66
|
## Path references in installed content
|
|
67
67
|
|
|
68
68
|
Installable content is rewritten at install time. Author cross-references in one of three forms, depending on intent:
|
|
69
69
|
|
|
70
|
-
- **Runtime references**: Paths that the agent reads or executes at runtime. Use `[text](relative/path.md)` for a Markdown link, or `{harness_home_dir}/...` inside inline code or a command (e.g., `{harness_home_dir}/skills/_data/work-types.json`), the form that a partial inlined at several depths can use. Both name a file by its place in the content tree, and the pipeline resolves both to where that file is deployed: A target naming a skill deployed by the same run resolves where that run wrote it, a target in one of the owning source's support entries resolves into that source's namespace, `skills/_sources/<name>/`, and anything else resolves to the harness home. `sync --global` anchors the first two under the harness home, and bare `sync` under the project root. Every other `{harness_home_dir}` expands to the platform home (e.g., `~/.claude`), where `scripts/`
|
|
70
|
+
- **Runtime references**: Paths that the agent reads or executes at runtime. Use `[text](relative/path.md)` for a Markdown link, or `{harness_home_dir}/...` inside inline code or a command (e.g., `{harness_home_dir}/skills/_data/work-types.json`), the form that a partial inlined at several depths can use. Both name a file by its place in the content tree, and the pipeline resolves both to where that file is deployed: A target naming a skill deployed by the same run resolves where that run wrote it, a target in one of the owning source's support entries resolves into that source's namespace, `skills/_sources/<name>/`, and anything else resolves to the harness home. `sync --global` anchors the first two under the harness home, and bare `sync` under the project root. Every other `{harness_home_dir}` expands to the platform home (e.g., `~/.claude`), where `scripts/` is deployed.
|
|
71
71
|
- **Source-tree citations**: Prose pointing the reader to the canonical implementation, like a doc reference. A bare `packages/guidance/content/...` path is acceptable in this case, but the file must be added to the allowlist in `packages/guidance/content/__tests__/content-path-conventions.unit.test.ts`.
|
|
72
72
|
- **Self-referential prose** about the source tree itself (e.g., this paragraph) is treated as a source-tree citation.
|
|
73
73
|
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
## Style
|
|
2
2
|
|
|
3
|
-
-
|
|
3
|
+
- Follow `.editorconfig`, and fill new comments to its `max_line_length`.
|
|
4
4
|
- Order lists and collections logically (alphabetically unless there is a good reason to sort or group differently).
|
|
5
5
|
- Use long-form CLI options (`--force`, not `-f`) in generated commands and scripts.
|
|
6
6
|
- Structure code so that the primary logic comes first; place helper functions at the end.
|
|
@@ -34,7 +34,7 @@ The library's behavior belongs in the library's docs. A helper's contract belong
|
|
|
34
34
|
|
|
35
35
|
**4. The derivation test: Do the listed cases follow from one rule?** Then state the rule.
|
|
36
36
|
|
|
37
|
-
A comment that enumerates the cases below it copies each case's own description, and the copy drifts: The enumeration keeps a name that the code has since renamed, or it places one case on both sides of a distinction. State the invariant that generates the cases, and let each case's own description
|
|
37
|
+
A comment that enumerates the cases below it copies each case's own description, and the copy drifts: The enumeration keeps a name that the code has since renamed, or it places one case on both sides of a distinction. State the invariant that generates the cases, and let each case's own description state its specifics. An exception is worth naming once, beside the rule.
|
|
38
38
|
|
|
39
39
|
Tells: The same name appearing in two of the comment's lists, a run of backticked member names already documented at their own declarations below, and a list whose length tracks the number of members or branches below it.
|
|
40
40
|
|
|
@@ -52,6 +52,10 @@ The helper reports every determiner "no" under this rule, as shape 9, in any pos
|
|
|
52
52
|
|
|
53
53
|
### Words to look for
|
|
54
54
|
|
|
55
|
+
<!-- rule: overused-word 1 -->
|
|
56
|
+
|
|
57
|
+
The helper reports every sentence that contains one of these words or an inflection of one under this rule. Report a site of a listed word under `overused-word`, and every other site that breaks the plain-speech rule under `plain-speech`.
|
|
58
|
+
|
|
55
59
|
Ten words recur in this corpus in uses for which a word naming the relation exists. Each is a search term rather than a rule, as a shape is: A match is a candidate for the rule's tests. When an entry names a sense that stays, a use in that sense is not a candidate.
|
|
56
60
|
|
|
57
61
|
- **carry**: "the change carries a flag". Instead: has, includes, declares, sets, states.
|
|
@@ -2,4 +2,5 @@
|
|
|
2
2
|
|
|
3
3
|
- Default to current best practices. Before recommending an approach, verify it reflects the current state of the ecosystem, not a pattern that was standard two years ago.
|
|
4
4
|
- When unsure whether your knowledge is current, say so and look it up rather than presenting a possibly outdated approach as the answer.
|
|
5
|
+
- Before weighing options for a design problem, name the solutions that current best practice applies to that kind of problem and the conditions under which each one fits, then start from the one whose conditions hold. Label an option that departs from all of them as non-standard, and state why none of them fits. When the standard solution requires revising an existing API, recommend the revision rather than an addition that works around the current contract.
|
|
5
6
|
- Prefer CLI tools over web UI instructions. When a task can be done via a CLI command (e.g., `npm trust`, `gh repo edit`, `gh secret set`), recommend the command, not manual steps in a browser. When multiple commands need to be run, offer to write a script in the most suitable language (other things being equal, prefer bash and TypeScript), following the relevant coding conventions.
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
# The content-format contract against which this root is authored; see "Content-format version" in packages/agents/docs/project-declaration.md.
|
|
2
|
-
format:
|
|
2
|
+
format: 3
|
|
3
3
|
|
|
4
4
|
# The TypeScript helpers that `codeassembly bundle-helpers` bundles into this root, both paths relative to this file.
|
|
5
5
|
helpers:
|
|
@@ -33,6 +33,8 @@ helpers:
|
|
|
33
33
|
out: skills/revise-prose/revise-prose.mjs
|
|
34
34
|
- entry: ../src/streamline-guidance/cli.ts
|
|
35
35
|
out: skills/streamline-guidance/streamline-guidance.mjs
|
|
36
|
+
- entry: ../src/validate-preferences/cli.ts
|
|
37
|
+
out: scripts/validate-preferences.mjs
|
|
36
38
|
- entry: ../src/describe-change/cli.ts
|
|
37
39
|
out: scripts/describe-change.mjs
|
|
38
40
|
- entry: ../src/select-lede-exemplars/cli.ts
|
|
@@ -47,3 +49,11 @@ helpers:
|
|
|
47
49
|
out: skills/index-prototypes/index-prototypes.mjs
|
|
48
50
|
- entry: ../src/select-pr-ticket/cli.ts
|
|
49
51
|
out: skills/review-gh-pr/select-pr-ticket.mjs
|
|
52
|
+
- entry: ../src/resolve-ticket-target/cli.ts
|
|
53
|
+
out: skills/create-ticket/resolve-ticket-target.mjs
|
|
54
|
+
- entry: ../src/triage-spike-findings/cli.ts
|
|
55
|
+
out: skills/triage-spike-findings/triage-spike-findings.mjs
|
|
56
|
+
- entry: ../src/check-branch-currency/cli.ts
|
|
57
|
+
out: scripts/check-branch-currency.mjs
|
|
58
|
+
- entry: ../src/check-prose/cli.ts
|
|
59
|
+
out: scripts/check-prose.mjs
|
|
@@ -6,6 +6,6 @@ members: '@library'
|
|
|
6
6
|
|
|
7
7
|
# All
|
|
8
8
|
|
|
9
|
-
The whole-catalog collection. `members: '@library'` resolves to every rulebook, skill, and subagent in the content library, computed at resolution time so that a newly added artifact
|
|
9
|
+
The whole-catalog collection. `members: '@library'` resolves to every rulebook, skill, and subagent in the content library, computed at resolution time so that the resolver includes a newly added artifact automatically, without an edit here. Collections are excluded: The resolver never emits them, and "every collection" would be self-referential.
|
|
10
10
|
|
|
11
|
-
This is the
|
|
11
|
+
This is the fallback, not the expected declaration. It does not make any claim about its members: It deploys the vetted, the unexamined, and the artifacts deliberately left out of every collection alike, and it includes a newly added artifact before anyone has read it. A consumer should declare the collections whose dispositions it wants instead, and declare this one only to deploy the whole catalog.
|
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: atlassian
|
|
3
3
|
description: Skills that act on Bitbucket pull requests and Jira work items.
|
|
4
|
+
disposition: opt-in
|
|
4
5
|
members:
|
|
5
6
|
skills:
|
|
6
7
|
- create-bitbucket-pr
|
|
@@ -13,4 +14,4 @@ members:
|
|
|
13
14
|
|
|
14
15
|
Every member acts on one of Atlassian's hosted products: creating, reviewing, and merging Bitbucket pull requests, and creating and updating Jira work items. A consumer should declare this collection only if one of those products is in use.
|
|
15
16
|
|
|
16
|
-
|
|
17
|
+
Artifacts outside this collection do not require any member. `create-pr`, `merge-pr`, `review-pr`, and `create-ticket` each name one through an optional invocation token, and `codeassembly validate` reports a token naming a member that is written in its required form.
|