codeassembly-guidance 0.1.0 → 0.3.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 (165) hide show
  1. package/.meta/changelog.json +984 -0
  2. package/CHANGELOG.md +240 -0
  3. package/README.md +45 -99
  4. package/bin/codeassembly-validate-preferences.js +18 -0
  5. package/content/_partials/README.md +21 -5
  6. package/content/_partials/comment-discipline.md +1 -1
  7. package/content/_partials/diff-audit-checklist.md +1 -0
  8. package/content/_partials/kb-standard-tags.md +7 -0
  9. package/content/_partials/plain-speech-calibration.md +4 -0
  10. package/content/_partials/technical-recommendations.md +1 -0
  11. package/content/codeassembly-content.yaml +17 -1
  12. package/content/collections/all.md +2 -2
  13. package/content/collections/atlassian.md +2 -1
  14. package/content/collections/recommended.md +9 -2
  15. package/content/collections/triage.md +3 -67
  16. package/content/collections/williamthorsen.md +2 -1
  17. package/content/guidance/README.md +1 -1
  18. package/content/guidance/rulebooks/accessibility-conventions.md +23 -5
  19. package/content/guidance/rulebooks/cli-conventions.md +206 -0
  20. package/content/guidance/rulebooks/codeassembly-content-specification.md +50 -10
  21. package/content/guidance/rulebooks/commit-conventions.md +5 -4
  22. package/content/guidance/rulebooks/live-worktree-policy.md +3 -2
  23. package/content/guidance/rulebooks/readme-conventions.md +3 -3
  24. package/content/guidance/rulebooks/shared-data-conventions.md +2 -2
  25. package/content/guidance/rulebooks/shell-conventions.md +17 -23
  26. package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
  27. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +18 -12
  28. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +3 -3
  29. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +6 -6
  30. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +1 -1
  31. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +7 -7
  32. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +28 -1
  33. package/content/guidance/shared/AGENTS.md +39 -4
  34. package/content/scripts/README.md +5 -2
  35. package/content/scripts/check-branch-currency.mjs +11 -0
  36. package/content/scripts/check-prose.mjs +171 -0
  37. package/content/scripts/describe-change.mjs +98 -98
  38. package/content/scripts/manage-jira-ticket.mjs +99 -94
  39. package/content/scripts/resolve-frontmatter.sh +1 -1
  40. package/content/scripts/resolve-review-run.mjs +9 -9
  41. package/content/scripts/select-lede-exemplars.mjs +87 -87
  42. package/content/scripts/validate-preferences.mjs +146 -0
  43. package/content/skills/_data/action-items.md +2 -0
  44. package/content/skills/_data/artifact-conventions.md +64 -16
  45. package/content/skills/_data/branch-currency.md +36 -0
  46. package/content/skills/_data/change-record.md +2 -2
  47. package/content/skills/_data/complexity-classification.md +1 -1
  48. package/content/skills/_data/design-priorities.md +15 -4
  49. package/content/skills/_data/project-stage.md +32 -0
  50. package/content/skills/_data/recommendation-gradient.md +9 -7
  51. package/content/skills/_data/scope-and-deferral.md +1 -1
  52. package/content/skills/_data/spike-conventions.md +21 -6
  53. package/content/skills/_data/ticket-evaluation.md +2 -2
  54. package/content/skills/_data/ticket-source-resolution.md +36 -3
  55. package/content/skills/_data/title-templates.md +22 -12
  56. package/content/skills/_partials/action-items.md +2 -2
  57. package/content/skills/_partials/apply-guidance-edits.md +5 -0
  58. package/content/skills/_partials/commit-title-rendering.md +1 -1
  59. package/content/skills/_partials/jira-task-list-flattening.md +1 -0
  60. package/content/skills/_partials/next-steps-after-plan.md +11 -11
  61. package/content/skills/_partials/option-format.md +18 -17
  62. package/content/skills/_partials/plan-template.md +7 -5
  63. package/content/skills/_partials/split-ticket-compose.md +1 -1
  64. package/content/skills/_partials/split-ticket-create.md +1 -1
  65. package/content/skills/_partials/ticket-and-plan-completeness.md +2 -2
  66. package/content/skills/_partials/ticket-composition.md +40 -0
  67. package/content/skills/_partials/ticket-criteria-conventions.md +3 -3
  68. package/content/skills/_partials/ticket-skeleton.md +15 -1
  69. package/content/skills/add-change-record/SKILL.md +2 -2
  70. package/content/skills/align-ticket-with-implementation/SKILL.md +3 -7
  71. package/content/skills/anti-patterns/SKILL.md +1 -1
  72. package/content/skills/assess-code-health/SKILL.md +127 -0
  73. package/content/skills/assess-code-health/assess-code-health.mjs +77 -0
  74. package/content/skills/assess-usability/SKILL.md +98 -0
  75. package/content/skills/capture-event/SKILL.md +4 -2
  76. package/content/skills/capture-event/capture-event.mjs +89 -89
  77. package/content/skills/capture-feedback/SKILL.md +1 -1
  78. package/content/skills/capture-lede-decision/SKILL.md +4 -4
  79. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +98 -98
  80. package/content/skills/collaborate/SKILL.md +3 -3
  81. package/content/skills/create-bitbucket-pr/SKILL.md +2 -1
  82. package/content/skills/create-commit/SKILL.md +1 -1
  83. package/content/skills/create-gh-pr/SKILL.md +28 -10
  84. package/content/skills/create-pr/SKILL.md +7 -6
  85. package/content/skills/create-ticket/SKILL.md +64 -23
  86. package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
  87. package/content/skills/derive-session-context/derive-session-context.mjs +83 -82
  88. package/content/skills/design-and-plan/SKILL.md +17 -18
  89. package/content/skills/groom-backlog/SKILL.md +8 -6
  90. package/content/skills/groom-backlog/groom-backlog.mjs +64 -62
  91. package/content/skills/implement-plan/SKILL.md +27 -23
  92. package/content/skills/index-prototypes/SKILL.md +86 -31
  93. package/content/skills/index-prototypes/index-prototypes.mjs +76 -16
  94. package/content/skills/kb-add/SKILL.md +4 -1
  95. package/content/skills/kb-add/kb-add.mjs +128 -128
  96. package/content/skills/kb-curate/SKILL.md +9 -7
  97. package/content/skills/kb-curate/kb-curate.mjs +103 -103
  98. package/content/skills/kb-edit/SKILL.md +5 -3
  99. package/content/skills/kb-edit/kb-edit.mjs +94 -94
  100. package/content/skills/kb-retrieve/kb-retrieve.mjs +86 -85
  101. package/content/skills/kb-retrieve-events/SKILL.md +20 -11
  102. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +86 -85
  103. package/content/skills/kb-update-events/SKILL.md +10 -7
  104. package/content/skills/kb-update-events/kb-update-events.mjs +110 -109
  105. package/content/skills/lesson-clusters/lesson-clusters.mjs +209 -0
  106. package/content/skills/merge-bb-pr/SKILL.md +1 -1
  107. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +5 -5
  108. package/content/skills/merge-pr/SKILL.md +11 -11
  109. package/content/skills/migrate-feedback-memories/SKILL.md +3 -2
  110. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +76 -76
  111. package/content/skills/plan/SKILL.md +2 -2
  112. package/content/skills/prepare-prototype-brief/SKILL.md +66 -14
  113. package/content/skills/pull-from-backlog/SKILL.md +3 -3
  114. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +83 -82
  115. package/content/skills/refine-guidance/SKILL.md +97 -0
  116. package/content/skills/refine-plan/SKILL.md +7 -3
  117. package/content/skills/refine-prototype/SKILL.md +113 -0
  118. package/content/skills/respond-to-review/SKILL.md +1 -1
  119. package/content/skills/review-bb-pr/SKILL.md +1 -1
  120. package/content/skills/review-branch/SKILL.md +354 -3
  121. package/content/skills/review-criteria/SKILL.md +36 -3
  122. package/content/skills/review-gh-pr/select-pr-ticket.mjs +6 -6
  123. package/content/skills/revise-comments/SKILL.md +38 -5
  124. package/content/skills/revise-prose/SKILL.md +1 -1
  125. package/content/skills/revise-prose/revise-prose.mjs +119 -119
  126. package/content/skills/save-artifact/SKILL.md +3 -1
  127. package/content/skills/streamline-guidance/SKILL.md +11 -16
  128. package/content/skills/streamline-guidance/streamline-guidance.mjs +86 -86
  129. package/content/skills/summarize-change/SKILL.md +23 -14
  130. package/content/skills/testing-conventions/SKILL.md +81 -8
  131. package/content/skills/triage-feedback/SKILL.md +150 -0
  132. package/content/skills/triage-feedback/triage-feedback.mjs +70 -0
  133. package/content/skills/triage-spike-findings/SKILL.md +113 -0
  134. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +73 -0
  135. package/content/skills/typescript-testing-conventions/SKILL.md +50 -1
  136. package/content/skills/update-jira-ticket/SKILL.md +20 -8
  137. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +7 -7
  138. package/content/skills/update-project-guidance/SKILL.md +12 -12
  139. package/content/subagents/_data/claude.yaml +6 -0
  140. package/content/subagents/_data/rovo.yaml +12 -2
  141. package/content/subagents/canary.md +2 -1
  142. package/content/subagents/code-health-assessor.md +98 -0
  143. package/content/subagents/disposition-challenger.md +78 -0
  144. package/content/subagents/entry-drafter.md +14 -10
  145. package/content/subagents/feedback-triage-challenger.md +81 -0
  146. package/content/subagents/handoff-reviewer.md +2 -2
  147. package/content/subagents/lesson-clusterer.md +68 -0
  148. package/content/subagents/plan-reviewer.md +1 -1
  149. package/content/subagents/prose-reviser.md +4 -2
  150. package/content/subagents/ticket-assessor.md +9 -6
  151. package/content/subagents/usability-assessor.md +157 -0
  152. package/package.json +21 -17
  153. package/schemas/preferences.v1.json +50 -7
  154. package/schemas/work-types.v1.json +1 -1
  155. package/content/_partials/code-descriptions.md +0 -4
  156. package/content/_partials/code-style.md +0 -7
  157. package/content/_partials/live-repo-writes.md +0 -13
  158. package/content/_partials/reduced-object-relative.md +0 -28
  159. package/content/_partials/test-structure-audit-checklist.md +0 -7
  160. package/content/skills/_partials/acceptance-criteria-scaffold.md +0 -15
  161. package/content/skills/_partials/next-steps-after-review.md +0 -350
  162. package/content/skills/_partials/ticket-concision.md +0 -18
  163. package/content/skills/_partials/ticket-placement.md +0 -14
  164. package/content/skills/_partials/ticket-skeleton-tiers.md +0 -6
  165. package/content/skills/testing-conventions/mistakes.md +0 -1
@@ -462,7 +462,7 @@ emit_yaml_flow_list() {
462
462
 
463
463
  # Emits a top-level YAML flow list from items accumulated by `--extra-list-item`,
464
464
  # splitting on ASCII US rather than on `,` so that an item containing a comma
465
- # survives whole. Each item is quoted as `emit_yaml_flow_list` quotes its own.
465
+ # stays whole. Each item is quoted as `emit_yaml_flow_list` quotes its own.
466
466
  emit_yaml_flow_list_items() {
467
467
  local key="$1" raw="$2"
468
468
  local out="" first=1 item
@@ -1,12 +1,12 @@
1
1
  import { createRequire as __cjsCreateRequire } from 'node:module';
2
2
  const require = __cjsCreateRequire(import.meta.url);
3
- var M=Object.defineProperty;var i=(e,n)=>M(e,"name",{value:n,configurable:!0});import{realpathSync as F}from"node:fs";import c from"node:process";import{fileURLToPath as I}from"node:url";function E(e){return e instanceof Error||Object.prototype.toString.call(e)==="[object Error]"}i(E,"isError");function f(e){try{return E(e)&&typeof e.message=="string"&&e.message!==""?e.message:String(e)}catch{return"[unstringifiable value]"}}i(f,"describeError");function h(e,n){let r=[],t=[];for(let o=0;o<e.length;o+=1){let s=e[o];if(s===void 0)continue;if(!s.startsWith("--")){r.push(s);continue}let u=T(s,n);if(u===null)throw new Error(`unknown flag: ${s}`);let{spec:a,inlineValue:g}=u;if(!a.takesValue){if(g!==null)throw new Error(`--${a.name} does not take a value`);t.push({name:a.name,value:null});continue}if(g!==null){t.push({name:a.name,value:g});continue}let p=e[o+1]??null;if(p===null||p.startsWith("--"))throw new Error(`--${a.name} requires a value`);t.push({name:a.name,value:p}),o+=1}return{positionals:r,flags:t}}i(h,"scanFlags");function y(e){let n={};for(let{name:r,value:t}of e)t!==null&&(n[r]=t);return n}i(y,"valueFlagMap");function T(e,n){for(let r of n)for(let t of[r.name,...r.aliases??[]]){let o=`--${t}`;if(e===o)return{spec:r,inlineValue:null};if(e.startsWith(`${o}=`))return{spec:r,inlineValue:e.slice(o.length+1)}}return null}i(T,"matchFlag");import{mkdir as b,readdir as A}from"node:fs/promises";import w from"node:path";function P(e,n){return D(e)&&e.code===n}i(P,"isErrorCode");function x(e){return P(e,"ENOENT")}i(x,"isEnoent");function D(e){return typeof e=="object"&&e!==null}i(D,"isObject");var v="interactive",V=new RegExp(String.raw`^(\d{8}-\d{6}Z)-${v}$`),j=/^(\d{8}-\d{6}Z)_(?:overseer|reviewer)_review\.md$/,_=/^\d{8}-\d{6}Z$/;async function d(e){let n=k(await $(e,"directory"),V);return n===void 0?void 0:w.join(e,n)}i(d,"findActiveRun");async function R(e){let n=await d(e);if(n===void 0)throw new Error(`no ${v} run directory found in ${e}`);let r=k(await $(n,"file"),j);if(r===void 0)throw new Error(`no reviewer or overseer review found in ${n}`);return{reviewPath:w.join(n,r),runDir:n}}i(R,"findLatestReview");async function N(e,n){if(!_.test(n))throw new Error(`timestamp must be UTC YYYYMMDD-HHMMSSZ, got '${n}'`);let r=await d(e);if(r!==void 0)return r;let t=w.join(e,`${n}-${v}`);return await b(t,{recursive:!0}),t}i(N,"openRun");async function $(e,n){try{return(await A(e,{withFileTypes:!0})).filter(t=>n==="directory"?t.isDirectory():t.isFile()).map(t=>t.name)}catch(r){if(x(r))return[];throw r}}i($,"listEntryNames");function k(e,n){let r;for(let t of e){let o=n.exec(t)?.[1];o!==void 0&&(r===void 0||o>r.timestamp||o===r.timestamp&&t>r.name)&&(r={name:t,timestamp:o})}return r?.name}i(k,"selectNewest");var Y=[{name:"ticket-dir",takesValue:!0},{name:"timestamp",takesValue:!0}],l=`usage: resolve-review-run active --ticket-dir <dir>
3
+ var P=Object.defineProperty;var i=(e,n)=>P(e,"name",{value:n,configurable:!0});import m from"node:process";function E(e){return e instanceof Error||Object.prototype.toString.call(e)==="[object Error]"}i(E,"isError");function c(e){try{return E(e)&&typeof e.message=="string"&&e.message!==""?e.message:String(e)}catch{return"[unstringifiable value]"}}i(c,"describeError");import{realpathSync as h}from"node:fs";import y from"node:process";import{fileURLToPath as b}from"node:url";function x(e,n){let r=y.argv[1];if(r===void 0)return!1;try{return h(b(e))===h(r)}catch(t){return y.stderr.write(`${n}: warning: could not determine entry point: ${c(t)}
4
+ `),!0}}i(x,"isEntryPoint");function R(e,n){let r=[],t=[];for(let o=0;o<e.length;o+=1){let s=e[o];if(s===void 0)continue;if(!s.startsWith("--")){r.push(s);continue}let u=D(s,n);if(u===null)throw new Error(`unknown flag: ${s}`);let{spec:a,inlineValue:g}=u;if(!a.takesValue){if(g!==null)throw new Error(`--${a.name} does not take a value`);t.push({name:a.name,value:null});continue}if(g!==null){t.push({name:a.name,value:g});continue}let p=e[o+1]??null;if(p===null||p.startsWith("--"))throw new Error(`--${a.name} requires a value`);t.push({name:a.name,value:p}),o+=1}return{positionals:r,flags:t}}i(R,"scanFlags");function N(e){let n={};for(let{name:r,value:t}of e)t!==null&&(n[r]=t);return n}i(N,"valueFlagMap");function D(e,n){for(let r of n)for(let t of[r.name,...r.aliases??[]]){let o=`--${t}`;if(e===o)return{spec:r,inlineValue:null};if(e.startsWith(`${o}=`))return{spec:r,inlineValue:e.slice(o.length+1)}}return null}i(D,"matchFlag");import{mkdir as j,readdir as _}from"node:fs/promises";import w from"node:path";function A(e,n){return V(e)&&e.code===n}i(A,"isErrorCode");function $(e){return A(e,"ENOENT")}i($,"isEnoent");function V(e){return typeof e=="object"&&e!==null}i(V,"isObject");var v="interactive",I=new RegExp(String.raw`^(\d{8}-\d{6}Z)-${v}$`),Y=/^(\d{8}-\d{6}Z)_(?:overseer|reviewer)_review\.md$/,L=/^\d{8}-\d{6}Z$/;async function f(e){let n=M(await S(e,"directory"),I);return n===void 0?void 0:w.join(e,n)}i(f,"findActiveRun");async function k(e){let n=await f(e);if(n===void 0)throw new Error(`${e} does not contain an ${v} run directory`);let r=M(await S(n,"file"),Y);if(r===void 0)throw new Error(`${n} does not contain a reviewer or overseer review`);return{reviewPath:w.join(n,r),runDir:n}}i(k,"findLatestReview");async function F(e,n){if(!L.test(n))throw new Error(`timestamp must be UTC YYYYMMDD-HHMMSSZ, got '${n}'`);let r=await f(e);if(r!==void 0)return r;let t=w.join(e,`${n}-${v}`);return await j(t,{recursive:!0}),t}i(F,"openRun");async function S(e,n){try{return(await _(e,{withFileTypes:!0})).filter(t=>n==="directory"?t.isDirectory():t.isFile()).map(t=>t.name)}catch(r){if($(r))return[];throw r}}i(S,"listEntryNames");function M(e,n){let r;for(let t of e){let o=n.exec(t)?.[1];o!==void 0&&(r===void 0||o>r.timestamp||o===r.timestamp&&t>r.name)&&(r={name:t,timestamp:o})}return r?.name}i(M,"selectNewest");var O=[{name:"ticket-dir",takesValue:!0},{name:"timestamp",takesValue:!0}],l=`usage: resolve-review-run active --ticket-dir <dir>
4
5
  resolve-review-run latest --ticket-dir <dir>
5
- resolve-review-run open --ticket-dir <dir> --timestamp <YYYYMMDD-HHMMSSZ>`;async function L(){try{let e=await C(c.argv.slice(2));c.stdout.write(`${JSON.stringify(e,null,2)}
6
- `)}catch(e){c.stderr.write(`resolve-review-run: ${f(e)}
7
- `),c.exit(1)}}i(L,"main");O()&&await L();function O(){let e=c.argv[1];if(e===void 0)return!1;try{return F(I(import.meta.url))===F(e)}catch(n){return c.stderr.write(`resolve-review-run: warning: could not determine entry point: ${f(n)}
8
- `),!1}}i(O,"isEntryPoint");function S(e,n){if(e.timestamp!==void 0)throw new Error(`${n} does not take --timestamp
9
- ${l}`)}i(S,"rejectTimestamp");function m(e,n){let r=e[n];if(r===void 0)throw new Error(`--${n} is required
10
- ${l}`);return r}i(m,"requireValue");async function C(e){let{flags:n,positionals:r}=h(e,Y),[t,...o]=r;if(o.length>0)throw new Error(`unexpected argument: ${o.join(" ")}
11
- ${l}`);let s=y(n);if(t==="active")return S(s,t),{runDir:await d(m(s,"ticket-dir"))??null};if(t==="latest"){S(s,t);let{reviewPath:u,runDir:a}=await R(m(s,"ticket-dir"));return{reviewPath:u,runDir:a}}if(t==="open")return{runDir:await N(m(s,"ticket-dir"),m(s,"timestamp"))};throw new Error(t===void 0?l:`unknown command: ${t}
12
- ${l}`)}i(C,"runCommand");
6
+ resolve-review-run open --ticket-dir <dir> --timestamp <YYYYMMDD-HHMMSSZ>`;async function C(){try{let e=await Z(m.argv.slice(2));m.stdout.write(`${JSON.stringify(e,null,2)}
7
+ `)}catch(e){m.stderr.write(`resolve-review-run: ${c(e)}
8
+ `),m.exit(1)}}i(C,"main");x(import.meta.url,"resolve-review-run")&&await C();function T(e,n){if(e.timestamp!==void 0)throw new Error(`${n} does not take --timestamp
9
+ ${l}`)}i(T,"rejectTimestamp");function d(e,n){let r=e[n];if(r===void 0)throw new Error(`--${n} is required
10
+ ${l}`);return r}i(d,"requireValue");async function Z(e){let{flags:n,positionals:r}=R(e,O),[t,...o]=r;if(o.length>0)throw new Error(`unexpected argument: ${o.join(" ")}
11
+ ${l}`);let s=N(n);if(t==="active")return T(s,t),{runDir:await f(d(s,"ticket-dir"))??null};if(t==="latest"){T(s,t);let{reviewPath:u,runDir:a}=await k(d(s,"ticket-dir"));return{reviewPath:u,runDir:a}}if(t==="open")return{runDir:await F(d(s,"ticket-dir"),d(s,"timestamp"))};throw new Error(t===void 0?l:`unknown command: ${t}
12
+ ${l}`)}i(Z,"runCommand");