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.
Files changed (101) hide show
  1. package/.meta/changelog.json +261 -0
  2. package/CHANGELOG.md +62 -0
  3. package/README.md +47 -29
  4. package/bin/codeassembly-validate-preferences.js +2 -8
  5. package/content/_partials/diff-audit-checklist.md +1 -0
  6. package/content/_partials/plain-speech.md +2 -2
  7. package/content/_partials/ticket-assessment.md +3 -3
  8. package/content/codeassembly-content.yaml +6 -0
  9. package/content/collections/recommended.md +6 -0
  10. package/content/collections/williamthorsen.md +2 -1
  11. package/content/guidance/rulebooks/accessibility-conventions.md +6 -3
  12. package/content/guidance/rulebooks/cross-repo-migration-conventions.md +27 -0
  13. package/content/guidance/rulebooks/ui-copy-conventions.md +2 -2
  14. package/content/guidance/rulebooks/visual-design-conventions.md +58 -0
  15. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +3 -18
  16. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +6 -2
  17. package/content/guidance/rulebooks/williamthorsen-visual-design-preferences.md +14 -0
  18. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +5 -3
  19. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +5 -20
  20. package/content/guidance/shared/AGENTS.md +2 -3
  21. package/content/scripts/README.md +1 -1
  22. package/content/scripts/check-branch-currency.mjs +7 -7
  23. package/content/scripts/check-prose.mjs +38 -38
  24. package/content/scripts/describe-change.mjs +32 -32
  25. package/content/scripts/manage-jira-ticket.mjs +148 -146
  26. package/content/scripts/validate-preferences.mjs +9 -9
  27. package/content/skills/_data/artifact-conventions.md +3 -3
  28. package/content/skills/_data/entry-points.md +1 -1
  29. package/content/skills/_data/reduced-object-relatives.md +15 -0
  30. package/content/skills/_data/spike-conventions.md +9 -2
  31. package/content/skills/_data/ticket-evaluation.md +3 -0
  32. package/content/skills/_partials/implementation-order-list.md +4 -4
  33. package/content/skills/_partials/merge-settled-criterion.md +1 -0
  34. package/content/skills/_partials/plan-template.md +1 -1
  35. package/content/skills/_partials/resolve-plan-and-ticket.md +2 -2
  36. package/content/skills/_partials/split-ticket-create.md +1 -1
  37. package/content/skills/_partials/ticket-criteria-conventions.md +2 -0
  38. package/content/skills/align-ticket-with-implementation/SKILL.md +2 -2
  39. package/content/skills/analyze-performance/SKILL.md +1 -1
  40. package/content/skills/assess-code-health/SKILL.md +4 -4
  41. package/content/skills/assess-code-health/assess-code-health.mjs +20 -20
  42. package/content/skills/assess-ticket/SKILL.md +3 -1
  43. package/content/skills/assess-ticket/next-steps-after-assessment.md +11 -14
  44. package/content/skills/assess-usability/SKILL.md +4 -4
  45. package/content/skills/capture-event/capture-event.mjs +30 -30
  46. package/content/skills/capture-lede-decision/SKILL.md +1 -1
  47. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +37 -37
  48. package/content/skills/collaborate/SKILL.md +1 -1
  49. package/content/skills/condense-branch/SKILL.md +18 -36
  50. package/content/skills/condense-branch/condense-branch.mjs +17 -0
  51. package/content/skills/create-bitbucket-pr/SKILL.md +9 -11
  52. package/content/skills/create-commit/SKILL.md +1 -1
  53. package/content/skills/create-devlog/SKILL.md +4 -4
  54. package/content/skills/create-gh-pr/SKILL.md +9 -11
  55. package/content/skills/create-pr/SKILL.md +9 -11
  56. package/content/skills/create-ticket/SKILL.md +22 -15
  57. package/content/skills/curate-feedback/SKILL.md +2 -2
  58. package/content/skills/derive-session-context/derive-session-context.mjs +103 -103
  59. package/content/skills/design-and-plan/SKILL.md +6 -6
  60. package/content/skills/groom-backlog/groom-backlog.mjs +15 -15
  61. package/content/skills/implement-plan/SKILL.md +1 -1
  62. package/content/skills/implementation-order/implementation-order.mjs +29 -29
  63. package/content/skills/index-prototypes/SKILL.md +2 -2
  64. package/content/skills/investigate-spike/SKILL.md +3 -3
  65. package/content/skills/list-gh-progress-items/SKILL.md +36 -0
  66. package/content/skills/list-gh-progress-items/list-gh-progress-items.mjs +68 -0
  67. package/content/skills/list-implementation-order/SKILL.md +2 -2
  68. package/content/skills/merge-bb-pr/SKILL.md +9 -11
  69. package/content/skills/merge-gh-pr/SKILL.md +9 -11
  70. package/content/skills/merge-pr/SKILL.md +10 -12
  71. package/content/skills/plan/SKILL.md +2 -2
  72. package/content/skills/prepare-prototype-brief/SKILL.md +2 -2
  73. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +22 -22
  74. package/content/skills/refine-plan/SKILL.md +3 -3
  75. package/content/skills/refine-prototype/SKILL.md +2 -1
  76. package/content/skills/respond-to-review/SKILL.md +4 -4
  77. package/content/skills/review-bb-pr/SKILL.md +1 -2
  78. package/content/skills/review-branch/SKILL.md +18 -13
  79. package/content/skills/review-criteria/SKILL.md +1 -1
  80. package/content/skills/review-gh-pr/SKILL.md +1 -2
  81. package/content/skills/review-pr/SKILL.md +2 -3
  82. package/content/skills/revise-prose/revise-prose.mjs +52 -52
  83. package/content/skills/save-artifact/SKILL.md +4 -6
  84. package/content/skills/save-plan/SKILL.md +2 -2
  85. package/content/skills/start-ticket/SKILL.md +1 -1
  86. package/content/skills/streamline-guidance/streamline-guidance.mjs +24 -24
  87. package/content/skills/summarize-change/SKILL.md +5 -4
  88. package/content/skills/summarize-chat/SKILL.md +2 -2
  89. package/content/skills/triage-feedback/SKILL.md +2 -2
  90. package/content/skills/triage-spike-findings/SKILL.md +26 -22
  91. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +19 -19
  92. package/content/skills/update-project-guidance/SKILL.md +1 -1
  93. package/content/skills/wrap-up/SKILL.md +4 -4
  94. package/content/skills/write-progress-report/SKILL.md +111 -0
  95. package/content/skills/write-progress-report/write-progress-report.mjs +150 -0
  96. package/content/subagents/disposition-challenger.md +7 -6
  97. package/content/subagents/entry-drafter.md +2 -0
  98. package/content/subagents/usability-assessor.md +3 -2
  99. package/package.json +11 -10
  100. package/schemas/preferences.v1.json +9 -1
  101. package/schemas/work-types.v1.json +1 -1
@@ -91,7 +91,7 @@ For each finding, assign one of these classes:
91
91
  - A finding belongs in the ambient tier only when it is absent from the tool's own output _and_ the obvious action goes wrong without it. A command table restates `--help`; a directory listing restates `ls`. Both are reference at best, and reference material injected at launch goes stale silently, because nothing fails when it drifts.
92
92
  - Do not duplicate general guidance or a rulebook loaded into the session; omit what they state. For a fact defined in a repository file, point to that file and add only what it does not state, per the "Documentation placement" section of the shared agent instructions. If a project-specific convention _extends_ a general one, include only the delta.
93
93
  - When unsure about scope, place the finding on the recommended side provisionally and collect every ambiguous finding into one review at the gate below, as multiple-choice questions when possible.
94
- - When asking option-style questions, follow [option format](#option-format). (Reinforces the rule in `AGENTS.md`: intentional redundancy.)
94
+ - When asking option-style questions, follow [option format](#option-format).
95
95
  - Content that is obvious from reading the code (e.g., "this project uses TypeScript") does not add any value. Include only what would save an agent from a wrong assumption or a slow discovery.
96
96
 
97
97
  <!-- include: ../_partials/action-items.md / -->
@@ -322,16 +322,16 @@ If Phase 3 did not create any tickets and did not drop any findings (e.g., a res
322
322
 
323
323
  Resolve the artifact path:
324
324
 
325
- - **Ticket-scoped** (when `ticket_id` from session context is non-null):
325
+ - **Ticket-scoped** (when `ticket_dir` from session context is non-null):
326
326
 
327
327
  ```
328
- {artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/{filename}
328
+ {ticket_dir}/{filename}
329
329
  ```
330
330
 
331
- - **Project-scoped fallback** (when `ticket_id` is null):
331
+ - **Project-scoped fallback** (when `ticket_dir` is null):
332
332
 
333
333
  ```
334
- {artifact_base_dir}/projects/{project_slug}/deferred-findings/{filename}
334
+ {project_artifact_dir}/deferred-findings/{filename}
335
335
  ```
336
336
 
337
337
  The `deferred-findings/` directory name is hardcoded; do not consult `artifact_paths` for it.
@@ -0,0 +1,111 @@
1
+ ---
2
+ name: write-progress-report
3
+ description: Write a customer-facing progress report from a set of work items, with one section per workstream, each with its health and a table of what needs the customer's input, what is done, what is in progress, and what is planned
4
+ user-invocable: true
5
+ ---
6
+
7
+ # Write progress report
8
+
9
+ Write a progress report for a reader outside the team. A source supplies the work items in one normalized shape, a bundled helper assigns each item its status and orders the rows of each workstream, you write every word that the customer reads, and the helper checks the links and renders the report.
10
+
11
+ The work does not have to be software, and the items do not have to come from a tracker: A file of items in the normalized shape is a source of its own.
12
+
13
+ **Announce at start:** "Using write-progress-report to write a progress report from {source}."
14
+
15
+ ## Arguments
16
+
17
+ | Argument | Description | Default |
18
+ | --------------------------- | ---------------------------------------------------------------------------------------------------- | --------------------------------- |
19
+ | `--items <path>` | A JSON file of items in the [item contract](#item-contract). It replaces the source. | None |
20
+ | `--source <name>` | The tracker that supplies the items. `github` is the one with a delegate. | The project's ticket platform |
21
+ | `--scope <query>` | Which items to read, in the source's own query language, passed to the delegate as written. | Every item that the source holds |
22
+ | `--period <start>[..<end>]` | The completion dates, inclusive, of the done items to report. Other items are always reported. | Every done item; the end is today |
23
+ | `--format <name>` | The format in which to render the report: `markdown`, or `confluence` for Confluence storage format. | `markdown` |
24
+
25
+ ## Item contract
26
+
27
+ The file is `{ "workstreams": [ ... ], "items": [ ... ] }`, and `workstreams` is optional. The helper rejects a field that the contract does not define.
28
+
29
+ Each item states facts, never a status:
30
+
31
+ | Field | Type | Meaning |
32
+ | ------------- | ---------------- | --------------------------------------------------------------------------- |
33
+ | `id` | string | The item's identifier in its source; never rendered |
34
+ | `title` | string | The item's title in its source |
35
+ | `description` | string or `null` | Context for the details; never rendered |
36
+ | `sources` | string array | Where the item is recorded, usually internal; never rendered |
37
+ | `workstream` | string or `null` | The `id` of the item's workstream |
38
+ | `closed` | boolean | Whether the item is closed |
39
+ | `completed` | boolean | Whether a closed item was closed as completed |
40
+ | `started` | boolean | Whether work on an open item has started |
41
+ | `needsInput` | boolean | Whether an open item is an ask of the customer |
42
+ | `completedOn` | date or `null` | UTC `YYYY-MM-DD` on which the item was completed; required for one that was |
43
+ | `targetOn` | date or `null` | UTC `YYYY-MM-DD` by which the item is expected to be completed |
44
+ | `neededBy` | date or `null` | UTC `YYYY-MM-DD` by which the customer's input is needed |
45
+
46
+ A workstream is `{ "id", "title", "health"?, "note"? }`, in which `health` is `on-track`, `at-risk`, or `off-track`. An item may name a workstream that the file does not declare.
47
+
48
+ ## Process
49
+
50
+ Every helper command prints one JSON result. When a result has `ok: false`, stop and report its `message` as written, except where a step says otherwise.
51
+
52
+ ### 1. Obtain the items
53
+
54
+ - With `--items`, use that path, and skip to step 2.
55
+ - Otherwise, take the source from `--source`, or else from the [platform resolution cascade](../_data/ticket-source-resolution.md#platform-resolution-cascade).
56
+ - For `github`, create the output path with `mktemp "${TMPDIR:-/tmp}/progress-items.XXXXXX"` and invoke {skill?:list-gh-progress-items} with that path, `--scope`, and the needs-input label when the bound guidance names one. It returns the path of the items file.
57
+ - For any other source, stop, and report that no delegate reads it and that `--items` accepts a file of items in the [item contract](#item-contract).
58
+
59
+ ### 2. Assemble the sections
60
+
61
+ Create a path with `mktemp "${TMPDIR:-/tmp}/progress-assembled.XXXXXX"`, then write the result to it:
62
+
63
+ ```bash
64
+ node {harness_home_dir}/skills/write-progress-report/write-progress-report.mjs assemble --items {items path} [--period {period}] > {assembled path}
65
+ ```
66
+
67
+ Read the result from that file. It contains `sections` in report order, each with its `workstream` (or `null` for the items without one) and its `rows`. Each row contains the item's fields, its `status`, its `label`, its `date` cell, the `dateOn` that the cell shows or `null`, and whether it is `overdue`. The result also contains `lastUpdated`, the `period` or `null`, and the `omitted` items with their reasons.
68
+
69
+ ### 3. Write the text
70
+
71
+ <!-- guidance-hook: progress-report-preferences -->
72
+
73
+ Rules that bound guidance states for the customer, such as tone, which items to omit, which hosts are internal, and each workstream's health, take precedence over the defaults below.
74
+
75
+ Write every word that the customer reads into a file created with `mktemp "${TMPDIR:-/tmp}/progress-text.XXXXXX"`, in this shape, with one section per assembled section and one row per assembled row:
76
+
77
+ ```json
78
+ {
79
+ "sections": [
80
+ {
81
+ "workstream": "ws-invoicing",
82
+ "heading": "Invoicing",
83
+ "health": "at-risk",
84
+ "note": "The export waits on access to your test account.",
85
+ "rows": [{ "id": "#12", "workItem": "Spreadsheet export", "details": "Verified on our test site; we deploy it to yours next." }]
86
+ }
87
+ ]
88
+ }
89
+ ```
90
+
91
+ 1. **Heading:** Name each workstream as the customer knows it. The workstream's `title` comes from the source and may use internal wording.
92
+ 2. **Health:** Leave `health` out when the workstream declares one. Otherwise, propose it from the rows: `at-risk` when a row is `overdue`, `off-track` when the rows show that the workstream cannot meet its plan, and `on-track` otherwise. State the reason in `note` when the health is not `on-track`.
93
+ 3. **Work item:** A short title in the customer's terms. Never copy the source's title.
94
+ 4. **Details:** Markdown of one or more paragraphs or a list, using only links, emphasis, and inline code within them, which every format renders. Read the `title` and the `description` for what the item achieves, and state what the customer can now do, will be able to do, or must do, with the caveats and dependencies that the customer needs, such as "verified on our test site, deploying to yours next". For a needs-input row, state the ask and what it unblocks.
95
+ 5. **Links:** Attach each link to words of the text as a Markdown inline link, and link only to a place that the customer can open, such as a deliverable, its documentation, or a demo. Never link to an item's `sources`, and never name an `id` or an internal name unless the bound guidance asks for them.
96
+
97
+ ## Output
98
+
99
+ Render the report, passing each host that the bound guidance lists as internal:
100
+
101
+ ```bash
102
+ node {harness_home_dir}/skills/write-progress-report/write-progress-report.mjs render --assembled {assembled path} --text {text path} [--format {format}] [--internal-host {host}]...
103
+ ```
104
+
105
+ When the result has `error: invalid-text`, its `message` names each problem by its place in the text file, such as `sections.0.rows.2.details`: Correct the text and render again. Stop on any other failure.
106
+
107
+ Print the result's `text` as one fenced block, ready to paste. Under `confluence`, the text is the body of a page in Confluence storage format, in which health and statuses are status lozenges and dates are date elements. Below the block, state in one line each:
108
+
109
+ - Each health that you proposed, with its reason.
110
+ - That the delegate reported `truncated`, when it did.
111
+ - How many items the helper omitted for each reason, leaving out a count of zero.