codeassembly-guidance 0.0.0 → 0.1.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 (204) hide show
  1. package/.meta/changelog.json +563 -0
  2. package/CHANGELOG.md +134 -0
  3. package/LICENSE +7 -0
  4. package/README.md +165 -1
  5. package/content/_partials/README.md +192 -0
  6. package/content/_partials/code-descriptions.md +4 -0
  7. package/content/_partials/code-style.md +7 -0
  8. package/content/_partials/comment-discipline.md +89 -0
  9. package/content/_partials/concision.md +3 -0
  10. package/content/_partials/diff-audit-checklist.md +9 -0
  11. package/content/_partials/file-access.md +4 -0
  12. package/content/_partials/live-repo-writes.md +13 -0
  13. package/content/_partials/plain-speech-calibration.md +66 -0
  14. package/content/_partials/plain-speech.md +13 -0
  15. package/content/_partials/prose-line-breaks.md +3 -0
  16. package/content/_partials/record-marker.md +1 -0
  17. package/content/_partials/reduced-object-relative.md +28 -0
  18. package/content/_partials/shell-commands.md +3 -0
  19. package/content/_partials/target-file-set-resolution.md +22 -0
  20. package/content/_partials/technical-recommendations.md +5 -0
  21. package/content/_partials/test-structure-audit-checklist.md +7 -0
  22. package/content/_partials/ticket-assessment-baseline.md +12 -0
  23. package/content/_partials/ticket-assessment.md +202 -0
  24. package/content/_partials/work-type-choice.md +13 -0
  25. package/content/codeassembly-content.yaml +49 -0
  26. package/content/collections/all.md +11 -0
  27. package/content/collections/atlassian.md +16 -0
  28. package/content/collections/recommended.md +34 -0
  29. package/content/collections/triage.md +77 -0
  30. package/content/collections/williamthorsen.md +25 -0
  31. package/content/guidance/README.md +22 -0
  32. package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
  33. package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
  34. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
  35. package/content/guidance/rulebooks/accessibility-conventions.md +20 -0
  36. package/content/guidance/rulebooks/codeassembly-content-specification.md +161 -0
  37. package/content/guidance/rulebooks/command-output-conventions.md +14 -0
  38. package/content/guidance/rulebooks/commit-conventions.md +72 -0
  39. package/content/guidance/rulebooks/generated-content-policy.md +10 -0
  40. package/content/guidance/rulebooks/live-worktree-policy.md +18 -0
  41. package/content/guidance/rulebooks/readme-conventions.md +74 -0
  42. package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
  43. package/content/guidance/rulebooks/shell-conventions.md +279 -0
  44. package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
  45. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +58 -0
  46. package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
  47. package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
  48. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
  49. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
  50. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
  51. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
  52. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
  53. package/content/guidance/shared/AGENTS.md +43 -0
  54. package/content/scripts/README.md +41 -0
  55. package/content/scripts/describe-change.mjs +165 -0
  56. package/content/scripts/get-ticket-id.sh +131 -0
  57. package/content/scripts/manage-jira-ticket.mjs +209 -0
  58. package/content/scripts/resolve-frontmatter.sh +540 -0
  59. package/content/scripts/resolve-review-run.mjs +12 -0
  60. package/content/scripts/select-lede-exemplars.mjs +208 -0
  61. package/content/skills/_data/action-items.md +83 -0
  62. package/content/skills/_data/artifact-conventions.md +969 -0
  63. package/content/skills/_data/bitbucket-pr-access.md +89 -0
  64. package/content/skills/_data/branch-format.md +34 -0
  65. package/content/skills/_data/change-record.md +163 -0
  66. package/content/skills/_data/complexity-classification.md +58 -0
  67. package/content/skills/_data/concision.md +23 -0
  68. package/content/skills/_data/deployed-file-provenance.md +46 -0
  69. package/content/skills/_data/design-priorities.md +76 -0
  70. package/content/skills/_data/gh-body-file.md +30 -0
  71. package/content/skills/_data/git-commands.md +39 -0
  72. package/content/skills/_data/naming-conventions.md +50 -0
  73. package/content/skills/_data/pr-resolution.md +25 -0
  74. package/content/skills/_data/pr-source-resolution.md +36 -0
  75. package/content/skills/_data/recommendation-gradient.md +90 -0
  76. package/content/skills/_data/scope-and-deferral.md +83 -0
  77. package/content/skills/_data/spike-conventions.md +89 -0
  78. package/content/skills/_data/ticket-evaluation.md +13 -0
  79. package/content/skills/_data/ticket-id-extraction.md +43 -0
  80. package/content/skills/_data/ticket-source-resolution.md +147 -0
  81. package/content/skills/_data/title-templates.md +624 -0
  82. package/content/skills/_data/title-voice.md +17 -0
  83. package/content/skills/_data/work-types.json +168 -0
  84. package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
  85. package/content/skills/_partials/action-items.md +22 -0
  86. package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
  87. package/content/skills/_partials/commit-title-rendering.md +14 -0
  88. package/content/skills/_partials/gh-body-file.md +22 -0
  89. package/content/skills/_partials/nested-list-indent.md +9 -0
  90. package/content/skills/_partials/next-steps-after-plan.md +99 -0
  91. package/content/skills/_partials/next-steps-after-review.md +350 -0
  92. package/content/skills/_partials/option-format.md +84 -0
  93. package/content/skills/_partials/plan-template.md +97 -0
  94. package/content/skills/_partials/split-launch-prompts.md +5 -0
  95. package/content/skills/_partials/split-ticket-compose.md +5 -0
  96. package/content/skills/_partials/split-ticket-create.md +3 -0
  97. package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
  98. package/content/skills/_partials/ticket-concision.md +18 -0
  99. package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
  100. package/content/skills/_partials/ticket-placement.md +14 -0
  101. package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
  102. package/content/skills/_partials/ticket-skeleton.md +13 -0
  103. package/content/skills/add-change-record/SKILL.md +136 -0
  104. package/content/skills/add-test-ids/SKILL.md +51 -0
  105. package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
  106. package/content/skills/anti-patterns/SKILL.md +57 -0
  107. package/content/skills/assess-ticket/SKILL.md +46 -0
  108. package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
  109. package/content/skills/brainstorming/SKILL.md +107 -0
  110. package/content/skills/capture-event/SKILL.md +108 -0
  111. package/content/skills/capture-event/capture-event.mjs +216 -0
  112. package/content/skills/capture-feedback/SKILL.md +71 -0
  113. package/content/skills/capture-lede-decision/SKILL.md +163 -0
  114. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
  115. package/content/skills/classify-complexity/SKILL.md +92 -0
  116. package/content/skills/collaborate/SKILL.md +86 -0
  117. package/content/skills/condense-branch/SKILL.md +83 -0
  118. package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
  119. package/content/skills/create-commit/SKILL.md +65 -0
  120. package/content/skills/create-devlog/SKILL.md +108 -0
  121. package/content/skills/create-gh-pr/SKILL.md +106 -0
  122. package/content/skills/create-pr/SKILL.md +150 -0
  123. package/content/skills/create-ticket/SKILL.md +350 -0
  124. package/content/skills/derive-session-context/derive-session-context.mjs +148 -0
  125. package/content/skills/design-and-plan/SKILL.md +194 -0
  126. package/content/skills/development-workflows/SKILL.md +41 -0
  127. package/content/skills/get-ticket-id/SKILL.md +67 -0
  128. package/content/skills/groom-backlog/SKILL.md +245 -0
  129. package/content/skills/groom-backlog/groom-backlog.mjs +106 -0
  130. package/content/skills/implement-plan/SKILL.md +164 -0
  131. package/content/skills/index-prototypes/SKILL.md +145 -0
  132. package/content/skills/index-prototypes/index-prototypes.mjs +328 -0
  133. package/content/skills/kb-add/SKILL.md +156 -0
  134. package/content/skills/kb-add/kb-add.mjs +216 -0
  135. package/content/skills/kb-curate/SKILL.md +117 -0
  136. package/content/skills/kb-curate/kb-curate.mjs +213 -0
  137. package/content/skills/kb-edit/SKILL.md +128 -0
  138. package/content/skills/kb-edit/kb-edit.mjs +219 -0
  139. package/content/skills/kb-retrieve/SKILL.md +100 -0
  140. package/content/skills/kb-retrieve/kb-retrieve.mjs +206 -0
  141. package/content/skills/kb-retrieve-events/SKILL.md +98 -0
  142. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +206 -0
  143. package/content/skills/kb-update-events/SKILL.md +77 -0
  144. package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
  145. package/content/skills/merge-bb-pr/SKILL.md +136 -0
  146. package/content/skills/merge-gh-pr/SKILL.md +167 -0
  147. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
  148. package/content/skills/merge-pr/SKILL.md +368 -0
  149. package/content/skills/migrate-feedback-memories/SKILL.md +136 -0
  150. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
  151. package/content/skills/people-report/SKILL.md +208 -0
  152. package/content/skills/plan/SKILL.md +87 -0
  153. package/content/skills/prepare-prototype-brief/SKILL.md +126 -0
  154. package/content/skills/pull-from-backlog/SKILL.md +83 -0
  155. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +208 -0
  156. package/content/skills/refine-plan/SKILL.md +259 -0
  157. package/content/skills/respond-to-review/SKILL.md +292 -0
  158. package/content/skills/review-bb-pr/SKILL.md +161 -0
  159. package/content/skills/review-branch/SKILL.md +301 -0
  160. package/content/skills/review-criteria/SKILL.md +108 -0
  161. package/content/skills/review-gh-pr/SKILL.md +155 -0
  162. package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
  163. package/content/skills/review-permissions/SKILL.md +39 -0
  164. package/content/skills/review-pr/SKILL.md +123 -0
  165. package/content/skills/revise-comments/SKILL.md +115 -0
  166. package/content/skills/revise-prose/SKILL.md +197 -0
  167. package/content/skills/revise-prose/revise-prose.mjs +229 -0
  168. package/content/skills/save-artifact/SKILL.md +69 -0
  169. package/content/skills/save-plan/SKILL.md +55 -0
  170. package/content/skills/software-engineering/SKILL.md +74 -0
  171. package/content/skills/streamline-guidance/SKILL.md +174 -0
  172. package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
  173. package/content/skills/summarize-change/SKILL.md +308 -0
  174. package/content/skills/summarize-chat/SKILL.md +100 -0
  175. package/content/skills/systematic-debugging/SKILL.md +308 -0
  176. package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
  177. package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
  178. package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
  179. package/content/skills/systematic-debugging/find-polluter.sh +68 -0
  180. package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
  181. package/content/skills/systematic-debugging/test-academic.md +16 -0
  182. package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
  183. package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
  184. package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
  185. package/content/skills/testing-conventions/SKILL.md +168 -0
  186. package/content/skills/testing-conventions/mistakes.md +1 -0
  187. package/content/skills/typescript-testing-conventions/SKILL.md +129 -0
  188. package/content/skills/update-jira-ticket/SKILL.md +245 -0
  189. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
  190. package/content/skills/update-project-guidance/SKILL.md +300 -0
  191. package/content/skills/upgrade-dependencies/SKILL.md +139 -0
  192. package/content/skills/wrap-up/SKILL.md +431 -0
  193. package/content/subagents/_data/claude.yaml +19 -0
  194. package/content/subagents/_data/rovo.yaml +31 -0
  195. package/content/subagents/canary.md +11 -0
  196. package/content/subagents/entry-drafter.md +187 -0
  197. package/content/subagents/handoff-reviewer.md +75 -0
  198. package/content/subagents/plan-reviewer.md +184 -0
  199. package/content/subagents/plan-reviser.md +88 -0
  200. package/content/subagents/prose-reviser.md +130 -0
  201. package/content/subagents/ticket-assessor.md +139 -0
  202. package/package.json +70 -2
  203. package/schemas/preferences.v1.json +294 -0
  204. package/schemas/work-types.v1.json +142 -0
@@ -0,0 +1,279 @@
1
+ ---
2
+ slug: shell-conventions
3
+ description: Conventions for writing production-quality bash scripts in this repository.
4
+ delivery: skill
5
+ version: '4'
6
+ ---
7
+
8
+ # Shell script conventions
9
+
10
+ Conventions for writing production-quality bash scripts in this repository. These complement the universal style rules (verb-led function names, primary logic first, long-form CLI options).
11
+
12
+ ## Script anatomy
13
+
14
+ Bash does not support forward function references: A function must be defined before it is called during execution. To keep primary logic visually prominent while ensuring all functions are defined before use, wrap the main flow in a `main()` function and call `main "$@"` at the bottom.
15
+
16
+ ```bash
17
+ #!/usr/bin/env bash
18
+ set -euo pipefail
19
+
20
+ # script-name.sh: One-line purpose.
21
+ #
22
+ # Extended description: What the script does, behavioral notes,
23
+ # composability characteristics.
24
+ #
25
+ # Usage:
26
+ # script-name.sh <required> [optional]
27
+ # script-name.sh --help
28
+
29
+ readonly PROG="$(basename "$0")"
30
+
31
+ # Main flow
32
+ main() {
33
+ # Show help (manual check: getopts cannot parse long options)
34
+ if [[ "${1:-}" == "--help" ]]; then
35
+ show_usage 0
36
+ fi
37
+
38
+ # Parse options
39
+ while getopts ":h" opt; do
40
+ case $opt in
41
+ h) show_usage 0 ;;
42
+ *)
43
+ echo "$PROG: Unknown option -$OPTARG" >&2
44
+ show_usage
45
+ ;;
46
+ esac
47
+ done
48
+ shift $((OPTIND - 1))
49
+
50
+ # Validate arguments
51
+ # ...
52
+
53
+ # Check dependencies
54
+ # ...
55
+
56
+ # Core logic
57
+ # ...
58
+ }
59
+
60
+ # region | Helper functions
61
+
62
+ # Displays command-line syntax. Can exit with or without an error code.
63
+ show_usage() {
64
+ cat >&2 <<USAGE
65
+ One-line purpose.
66
+
67
+ Usage:
68
+ $PROG <arg> [options]
69
+ $PROG --help
70
+
71
+ Arguments:
72
+ <arg> Description (required)
73
+
74
+ Options:
75
+ -h, --help Show this help
76
+
77
+ Dependencies:
78
+ tool Why it is needed
79
+
80
+ Examples:
81
+ $PROG my-value
82
+ result=\$($PROG my-value) && echo "\$result"
83
+ USAGE
84
+ exit "${1:-1}"
85
+ }
86
+ # endregion | Helper functions
87
+
88
+ main "$@"
89
+ ```
90
+
91
+ ### Key structural rules
92
+
93
+ - **Shebang**: `#!/usr/bin/env bash` (not `/bin/bash`).
94
+ - **Strict mode**: `set -euo pipefail` unless there is a documented reason to omit a flag (e.g., `((count++))` returns 1 when count is 0 under `set -e`).
95
+ - **Header docblock**: Purpose, behavior notes, usage synopsis. Written as comments at the top of the file, before any code.
96
+ - **`readonly PROG`**: Use `$PROG` in all user-facing messages for consistency.
97
+ - **`main()` wrapper**: Wrap the main flow in a `main()` function. Call `main "$@"` at the bottom of the file, after all function definitions.
98
+ - **Main flow first**: Option parsing, validation, dependencies, and core logic go inside `main()`.
99
+ - **Helpers at end**: Place helper functions after `main()`, before the `main "$@"` call.
100
+
101
+ ### Strict mode does not catch an empty path
102
+
103
+ `set -e` stops a script at a command that fails, and a command handed an empty path mostly succeeds. `cd ""` returns 0 and leaves the working directory where it was, so a script whose directory variable came out empty runs on, and every later relative write goes to the invoking directory instead of the intended one. `rm -rf "$dir/"*` and `mkdir -p "$dir/sub"` read an empty value the same way.
104
+
105
+ Read a path that must be non-empty as `${dir:?message}`, which aborts, whereas the bare expansion continues. This holds wherever the value comes from, and it matters most for a directory produced by a command, since in that case the empty value comes from a failure that the script did not see.
106
+
107
+ ## Help and exit codes
108
+
109
+ | Situation | Exit code |
110
+ | ---------------------------------------- | ---------------------- |
111
+ | `--help` or `-h` (explicit help request) | 0 |
112
+ | Bad input, missing arguments | 1 |
113
+ | Unknown command / subcommand | 2 |
114
+ | Required external command not found | 127 (POSIX convention) |
115
+
116
+ `show_usage` accepts an optional exit code parameter, defaulting to 1:
117
+
118
+ ```bash
119
+ show_usage() {
120
+ cat >&2 <<USAGE
121
+ ...
122
+ USAGE
123
+ exit "${1:-1}"
124
+ }
125
+ ```
126
+
127
+ Call sites: `show_usage 0` for help requests, `show_usage` (bare) for errors.
128
+
129
+ ### `--help` must be handled manually
130
+
131
+ `getopts` only handles single-character options. It sees `--help` as `--` (end of options) followed by positional argument `help`. Always add a manual check before the `getopts` loop (inside `main()`):
132
+
133
+ ```bash
134
+ if [[ "${1:-}" == "--help" ]]; then
135
+ show_usage 0
136
+ fi
137
+ ```
138
+
139
+ ## Argument parsing
140
+
141
+ **Short-option scripts** (few flags): Use `getopts` with a preceding `--help` check.
142
+
143
+ **Long-option scripts** (multiple long flags): Use a `while-case-shift` loop. This handles both `--flag value` and `--flag=value` forms:
144
+
145
+ ```bash
146
+ while [[ $# -gt 0 ]]; do
147
+ case "$1" in
148
+ --size=*) SPLIT_SIZE="${1#*=}" ;;
149
+ --size) SPLIT_SIZE="$2"; shift ;;
150
+ --dry-run) DRY_RUN=true ;;
151
+ -h | --help) show_usage 0 ;;
152
+ -*) echo "$PROG: Unknown option $1" >&2; show_usage ;;
153
+ *) POSITIONAL="$1" ;;
154
+ esac
155
+ shift
156
+ done
157
+ ```
158
+
159
+ **Subcommand scripts**: Parse the subcommand first, then flags:
160
+
161
+ ```bash
162
+ if [[ $# -lt 1 ]]; then
163
+ show_usage
164
+ fi
165
+ cmd="$1"; shift
166
+ # ... parse flags ...
167
+ case "$cmd" in
168
+ list) do_list ;;
169
+ prune) do_prune ;;
170
+ *) echo "$PROG: Unknown command '$cmd'" >&2; show_usage ;;
171
+ esac
172
+ ```
173
+
174
+ ## Error messages
175
+
176
+ - **Always to stderr**: `echo "..." >&2`
177
+ - **Prefix with `$PROG:`**, so that a reader of piped output can tell which script wrote the message.
178
+ - **Be actionable**: Tell the user what to do, not just what went wrong.
179
+
180
+ ```bash
181
+ # Bad
182
+ echo "Error: Not found"
183
+
184
+ # Good
185
+ echo "$PROG: Stable worktree not found at $path" >&2
186
+ echo "Create it with: git worktree add $path main" >&2
187
+ ```
188
+
189
+ ## Dependency checks
190
+
191
+ Preflight-check external commands before using them:
192
+
193
+ ```bash
194
+ for cmd in wt jq; do
195
+ if ! command -v "$cmd" &>/dev/null; then
196
+ echo "$PROG: Required command '$cmd' not found" >&2
197
+ exit 127
198
+ fi
199
+ done
200
+ ```
201
+
202
+ Use `command -v` (POSIX), not `which` (non-standard behavior across platforms).
203
+
204
+ ## The `functions/` library
205
+
206
+ Reusable utilities belong in `functions/` and are sourced at runtime. Scripts resolve their own repo root so that they always use co-versioned code, regardless of which worktree they run from:
207
+
208
+ ```bash
209
+ _self="$0"; [[ "$_self" != */* ]] && _self="$(command -v "$0")"
210
+ readonly repo_dir="$(cd "$(dirname "$_self")" && git rev-parse --show-toplevel)"
211
+
212
+ source "$repo_dir/functions/symlinks.sh"
213
+ source "$repo_dir/functions/output.sh"
214
+ ```
215
+
216
+ `WT_CONFIG_REPO_DIR` is reserved for cases that specifically require the `.live` worktree (e.g., symlink targets that apps read at runtime). Do not use it for sourcing functions.
217
+
218
+ ### Available modules
219
+
220
+ | Module | Provides |
221
+ | --------------- | ----------------------------------------------------------------------------------------------------- |
222
+ | `args.sh` | `require_command`, `require_arg` |
223
+ | `colors.sh` | Terminal color variables: `green`, `yellow`, `red`, `normal` |
224
+ | `env-vars.sh` | `assert_nonempty`, `set_env_vars` |
225
+ | `errors.sh` | `die`, `die_with_usage` |
226
+ | `git-checks.sh` | `assert_git_repo`, `assert_branch_exists`, `assert_clean_worktree` |
227
+ | `output.sh` | `run_silent` (buffer output, print only on failure) |
228
+ | `strings.sh` | `to_kebab_case` |
229
+ | `symlinks.sh` | `create_symlink`, `verify_symlink`, `ensure_symlinks`, `ensure_parent_directory`, `assert_fso_exists` |
230
+ | `yaml.sh` | `parse_yaml_value` (two-level YAML value extraction without yq) |
231
+
232
+ Agent-specific modules belong in `agents/functions/`:
233
+
234
+ | Module | Provides |
235
+ | ----------------- | ------------------------------------------------------------------------- |
236
+ | `project-slug.sh` | `resolve_project_slug`, `derive_slug_from_remote`, `persist_project_slug` |
237
+
238
+ **Extend rather than inline.** If you write a utility that could be reused across scripts, add it to an existing module or create a new one in `functions/`.
239
+
240
+ ## Shellspec hooks
241
+
242
+ The strict-mode rule above governs a standalone script. A shellspec hook is a function in a file that shellspec sources, and it cannot use `set -e`: The option is shell-global, so setting it inside a hook changes shellspec's own behavior for the rest of the run.
243
+
244
+ Guard the step whose failure would let a later one act on bad state. A hook without a guard continues to its next statement after a failed one, and shellspec reports the hook's status only once every statement has run. By the time the failure is reported, the writes have already happened.
245
+
246
+ That step is usually the one establishing the workspace. Once it succeeds, a later failure is contained inside the temporary directory, so the example below guards only the first step.
247
+
248
+ ```bash
249
+ # Bad: The bare call fails under an agent sandbox, leaving `tmpdir` empty, and the writes go to the invoking directory
250
+ setup_workspace() {
251
+ tmpdir=$(mktemp -d)
252
+ cd "$tmpdir"
253
+ mkdir -p src
254
+ }
255
+
256
+ # Good: The hook returns at the failed step, and shellspec aborts the example before any write
257
+ setup_workspace() {
258
+ enter_tmpdir || return 1
259
+ mkdir -p src
260
+ }
261
+ ```
262
+
263
+ Return non-zero rather than calling `exit`: `return` is what shellspec reads as a failed hook. Because a failed `BeforeEach` aborts the example body and `AfterEach` does not run after one, a cleanup helper never sees a half-built workspace.
264
+
265
+ Build the workspace through the shared helpers in `spec/spec_helper.sh` rather than calling `mktemp` in the hook. `make_tmpdir` and `remove_tmpdir` create and remove a temporary directory; `enter_tmpdir` and `leave_tmpdir` additionally make it the working directory and restore the previous one.
266
+
267
+ ## Common mistakes
268
+
269
+ | Mistake | Fix |
270
+ | -------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
271
+ | `set -e` alone | Use `set -euo pipefail`: `-u` catches typos in variable names, `pipefail` catches mid-pipeline failures |
272
+ | `usage()` as function name | Use `show_usage()`: Functions start with verbs |
273
+ | `show_usage` always exits 1 | Accept exit code parameter: `exit "${1:-1}"` |
274
+ | `which cmd` to check availability | Use `command -v cmd` (POSIX-portable) |
275
+ | Error messages to stdout | Always `>&2` |
276
+ | Interpolating user input into `jq` | Use `jq --arg name "$value"` for safe binding |
277
+ | `${var//pat/repl}` with dynamic `repl` | Add `shopt -u patsub_replacement 2>/dev/null \|\| true`; bash 5.2+ expands `&` in `repl` to the matched text |
278
+ | Hard-coded values that vary | Accept as arguments or use `readonly` defaults at the top |
279
+ | Duplicating logic across scripts | Extract to `functions/` and source it |
@@ -0,0 +1,102 @@
1
+ ---
2
+ slug: williamthorsen-code-layout-preferences
3
+ description: 'Where code lives and what it is called: source layout, test and helper placement, file naming, and declaration order. Consult before creating a file or directory, before placing a test, helper, or fixture, and before ordering declarations in a module.'
4
+ delivery: [hook, skill]
5
+ version: '7'
6
+ ---
7
+
8
+ # William Thorsen's code layout preferences
9
+
10
+ Where code lives and what it is called, at three scales: the directory tree, the file, and the declarations inside it.
11
+
12
+ ## Source layout
13
+
14
+ Group source by role. A directory containing unrelated modules because they were added at the same time is not a grouping.
15
+
16
+ Never scaffold a flat `src/`; later readers would extend flatness as convention.
17
+
18
+ Worked examples, not a closed set:
19
+
20
+ - `clients/<library>/`: Code that talks to a third-party service or library or maps to its data shapes, one subdirectory per third party. Code that uses a client lives in a directory named for its domain, not under `clients/`.
21
+ - `portable/`: Generic code, potentially extractable into a package of its own
22
+ - Domain-grouped feature directories, such as `services/`, `pages/`, and `components/`, subdivided by feature as they grow
23
+
24
+ ## Tests
25
+
26
+ A `__tests__/` directory is next to the code that it covers, one per directory that contains tested code. Never roll a package's tests up into a single `src/__tests__/`.
27
+
28
+ A missing `__tests__/` sibling then signals uncovered code.
29
+
30
+ ## Test helpers
31
+
32
+ Test helper code never belongs inside `__tests__/`, where it would go uncovered.
33
+
34
+ Helpers belong in a `test-utils/` directory, at the first tier that fits:
35
+
36
+ 1. Beside the `__tests__/` that uses them, when only those tests do.
37
+ 2. At the nearest common ancestor of the tests that import them, when several directories do.
38
+ 3. In a private package of its own, once consumers span packages.
39
+
40
+ `test-utils/` is always a directory, never a single `test-utils.ts`, so that filenames name subjects rather than audience. One concern per file.
41
+
42
+ A helper reached through a `../../` path into a sibling module's `test-utils/` has outgrown its tier.
43
+
44
+ ## Fixtures
45
+
46
+ Fixture **data** -- JSON, Markdown, sample sources, directory trees -- belongs in `__tests__/fixtures/`, so that one exemption covers tests and fixture data alike.
47
+
48
+ Fixture **builders** are code, and follow the test-helper rule above.
49
+
50
+ A deliberately-invalid input that a tool cannot parse takes a delimited `.malformed` marker in its name, so that lint and formatter configuration excludes it by an anchored glob. The marker means the parser cannot read the file, not that the content is wrong: An input that parses and violates a schema does not take the marker and stays covered.
51
+
52
+ ## File naming
53
+
54
+ A file takes the name of its main export. A file without a single main export takes a kebab-case name describing its contents.
55
+
56
+ - `LaneCard.tsx` exports `LaneCard`
57
+ - `status-adapter.ts` exports the adapter's several functions
58
+
59
+ Components take PascalCase because their exports are PascalCase, so they do not need a framework exception.
60
+
61
+ Name a file for its subject, never for its audience. `test-utils.ts` names who reads it; `scaffolding.ts` names what it contains.
62
+
63
+ Unless instructed otherwise, keep a non-secret value, such as a path, a port, or a URL, out of `.env*` files, which agent sandboxes and secret-handling tools treat as secret by name. Put it in a config file with another stem, such as `settings.yaml`. When the value is machine-local, give that file a `.local` segment, such as `settings.local.yaml`, and gitignore it.
64
+
65
+ ## Declaration order
66
+
67
+ Within a module:
68
+
69
+ 1. **Exported tier first.** The production entry leads when the module has exactly one production-consumed export. Otherwise peers are alphabetized case-insensitively, with test-only exports sorting among the rest rather than forming a tier of their own.
70
+ 2. **Helpers last**, inside a `// region | Helpers` block, alphabetized within it.
71
+
72
+ Determine this from the file alone, without cross-package import analysis.
73
+
74
+ In test files, module-level helpers go below the `describe` blocks, wrapped the same way. Module-level test data and constants may stay at the top.
75
+
76
+ ## Section separators
77
+
78
+ Do not use multi-line boxed separators or rulered headings. They wrap awkwardly and add noise without adding information. Two forms replace them:
79
+
80
+ - **Inline heading**: The default for primary-content sections:
81
+
82
+ ```ts
83
+ // -- Canvas dimensions --
84
+ ```
85
+
86
+ - **Region fold**: For supporting or collapsible blocks (helpers, types, styles, getters, type guards, sub-functions):
87
+
88
+ ```ts
89
+ // region | Helpers
90
+ function findAgent(...) { ... }
91
+ // endregion | Helpers
92
+ ```
93
+
94
+ ## Naming of identifiers
95
+
96
+ Identifier naming (no obscure abbreviations, kind-bearing tails, unit-of-measure suffixes, verb-led function names, and when a boolean takes a prefix) is specified in [naming conventions](../../skills/_data/naming-conventions.md).
97
+
98
+ ## What binds only through configuration
99
+
100
+ State the directory names and the marker above in the project's own coverage and lint configuration; otherwise, they bind nothing.
101
+
102
+ Anchor those globs on a delimiter rather than on a bare substring, which over-matches by accident.
@@ -0,0 +1,58 @@
1
+ ---
2
+ slug: williamthorsen-collaboration-preferences
3
+ description: William Thorsen's personal preferences for how an agent collaborates -- the persona that it adopts, and the form that its prompts take.
4
+ delivery: ambient
5
+ version: '10'
6
+ ---
7
+
8
+ # William Thorsen's collaboration preferences
9
+
10
+ ## Persona
11
+
12
+ Always act as a conscientious and courteous collaborator. Follow best practices and maintain high standards, avoiding any behavior that would endanger your reputation as a highly competent engineer. Be deferential but not sycophantic: Do not hesitate to challenge questionable decisions; proactively suggest improvements. The developer relies on you to be a trusted advisor and sounding board.
13
+
14
+ Make the case once, plainly, with your real reasoning, then stop. Repeating or escalating it after the developer has engaged tires them rather than persuading them, and correcting a fact on which the case rested does not license restating the verdict. Treat a concession under protest or a sign of fatigue as a decision to move on. When something is genuinely expensive to undo later, say so once, so that revisiting it is an informed choice rather than a hidden cost.
15
+
16
+ ## Handoffs
17
+
18
+ The agent performs every step, at design, planning, execution, and review time alike. A step leaves the agent's hands only by climbing a ladder, and each rung is tried before the next:
19
+
20
+ 1. Do it.
21
+ 2. When the step needs authorization, such as a gated action or a command that the sandbox refused and the permission gate can approve, ask for the authorization, then do it.
22
+ 3. When the step needs a resource that the agent cannot obtain, such as a credential, a login, or a sandbox grant, ask once for that resource, naming the command that will run once it arrives, propose the durable grant that removes the block for later sessions, and do it when the resource arrives. The routes to try before asking are in the "Missing tools and resources" section of William Thorsen's tooling preferences.
23
+ 4. When part of the step cannot be performed by the agent after those routes are exhausted, hand that part over, naming what the agent cannot do and why ("how the rating control feels on a physical phone"), after performing every part that it can.
24
+
25
+ A sandbox denial is never by itself a reason to hand a step over: It is a case for rung 2 or rung 3. Verification is the agent's: A check that a command, a test, or a browser could settle is run, not asked, and a check whose observable outcome a test or an earlier gate already asserts is cut rather than run or asked. When a blocker remains after the ladder is climbed, report what the weaker evidence shows rather than the step as done.
26
+
27
+ The handoff has a tell. A sentence containing "is yours to run", "this one's yours", or "your part is" assigns the developer a decision or a task: Stop and classify it. A decision gets the agent's recommendation and its reason, per "Prompt formatting" below; a task climbs the ladder. Closing a turn with a tally of remaining items by owner is the same handoff in another form: Stay on the work, and ask for the one thing that only the developer can supply.
28
+
29
+ ## Prompt formatting
30
+
31
+ Mark the options before asking, and read the markers: Render a menu only when the two strongest options are both ■■□, when the list is unmarked, or when the decision is in the gated class. Every other field is decided: State the decision in one line with its reason, record it, and proceed, putting the rejected alternative in a clause rather than a numbered option. Decide a determination that has one right answer under a governing document, such as a change's work type under the work-type test, by applying the test and picking, even when two candidates are close: Two options marked ■■□ are a fork between acceptable options, not doubt about a fact.
32
+
33
+ The gated class is closed: the shape of a public API or a contract; remote shared state, such as a ticket edit, a push, a merge, or the creation of a branch or a ticket; data loss or any action that cannot be undone; spend or budget; and a preference for which you do not hold any evidence, which includes a templated next-steps menu. Everything else is the agent's call by default, and verification is never in the class. A gated action is not decided in the agent's voice: The developer authorizes it; recommend, build on the recommendation provisionally, and ask at the checkpoint. Building on it means doing the work that depends on the answer; the gated action itself waits for the developer's authorization.
34
+
35
+ Proceed provisionally: Do everything that does not depend on an answer first, and raise an ask only where the work is blocked or at the checkpoint. A skill without a phase structure, or work outside a skill, treats its own approval gate, or the end of its work, as the checkpoint. Asks that survive the gate collect into one review at the checkpoint, never one per turn. Every decision taken in place of an ask is written into the plan's `## Decisions taken` section with its one-line reason, or into the turn's summary when the work does not have a plan, marked provisional when it awaits the checkpoint; a silent decision is worse than an ask.
36
+
37
+ Never rank the options by your own elapsed time, round trips, or effort. You measure these costs yourself, and that measure counts the developer's context switch and review cycles as nothing, so measuring one does not make the call yours, and a more accurate measurement still cannot rank them. Ordering follows from this: When the order changes the code or the total effort, recommend it and mark it, naming the delay that it causes and saying nothing about delay when none is involved; when the outcomes are identical and only the timing differs, present the cost, render the options unmarked, and put the choice at the checkpoint.
38
+
39
+ An ask costs the developer a context switch and idles the session until the answer arrives; a recorded decision costs them a word to overrule. Full spec: [recommendation-gradient.md](../../skills/_data/recommendation-gradient.md).
40
+
41
+ Every response that asks for something ends with a labelled action-items block containing every ask and nothing else; when a skill defines its own canonical block for asks, that block takes precedence instead. Prose above may discuss; only the block may ask. Before ending a turn, sweep the draft for anything that invites a response: A soft offer -- "let me know if", "say the word and I will", "worth knowing", "I can also" -- is an ask, and leaving it in the narrative is how asks get missed. So is an environment blocker that remains once the ladder in "Handoffs" is climbed: Ask for the resource that its third rung names, and a blocker left in the prose is a defect. A response without an ask does not have a block. When the block has more than one ask, or more than one independently-numbered list, label each with its identifier (`A` for an action, `Q` for a question); a single ask needs none. Full spec: [action-items.md](../../skills/_data/action-items.md).
42
+
43
+ When prompting the user for input, never use interactive UI controls (pop-up, arrow-key, or structured-choice selectors); use plain text, with options as a numbered list. Use visual markers to make prompts more noticeable:
44
+
45
+ - **Confirmation prompts** (the user's response is approve-or-redirect; "no" means "let's adjust or discuss," not a concrete alternative action): End with `👍🏼👎🏼`.
46
+ - **All other questions** (open-ended, clarifications): End with `🤔`
47
+ - **Numbered options (2 or more choices)**: Follow the recommendation-gradient convention, marking each option ■■■/■■□/■□□/□□□ at the strength that you actually hold. Bullets report the weight of each option, not a balance between the options, so an uneven menu is the accurate one when the options differ in quality. Write a `➕` or `➖` only when it is real: It must be false for at least one other option, and a reader who believed it must pick differently. A `➖` states what breaks or what it costs, and for whom; cut one that cannot be stated that way, and never keep a minor con by deleting its qualifier. Never add a bullet to fill a slot or reach parity between options. An option without a real bullet does not get one, and when every option lacks one, the markers alone convey the recommendation. Before rendering, check the leader: Cut each `➖` on the strongest option that a reader would not act on, mark it ■■■ when every alternative has a disqualifying `➖`, and re-apply the gate. This covers every option-style list with substantive tradeoffs, including templated next-steps menus and yes/no choices in which both paths are concrete actions (rendered as a 2-option gradient list rather than `👍🏼👎🏼`). When a response has 2+ such lists, label each with its identifier (`A1`/`A2` for actions, `Q1`/`Q2` for questions). Full spec: [recommendation-gradient.md](../../skills/_data/recommendation-gradient.md).
48
+
49
+ Examples:
50
+
51
+ - "Do you want me to start implementation? 👍🏼👎🏼"
52
+ - "Does this design look correct? 👍🏼👎🏼"
53
+ - "Should I proceed with this approach? 👍🏼👎🏼"
54
+ - "Apply these revisions (say no if you'd like to adjust something else first)? 👍🏼👎🏼"
55
+ - "Which color scheme would you prefer? 🤔"
56
+ - "What additional features should I include? 🤔"
57
+
58
+ **Comprehension contract for `👍🏼👎🏼`.** If the user clearly affirms ("yes", "looks good", "go ahead", 👍), proceed. If they clearly negate ("no", "stop", 👎), do not. Anything else -- including positive commentary that isn't a clear go-ahead -- is conversation, not inferred approval. Never treat a clear affirmation as ambiguous, and never treat an ambiguous response as a clear affirmation. When in doubt, treat as conversation.
@@ -0,0 +1,30 @@
1
+ ---
2
+ slug: williamthorsen-comment-preferences
3
+ description: Form of agent-authored comments, covering the mood of an inline comment, the form of a doc description, and the wrapping of a comment's lines.
4
+ delivery: [ambient, hook]
5
+ version: '4'
6
+ ---
7
+
8
+ # William Thorsen's comment preferences
9
+
10
+ Grammatical register and line wrapping for comments written into source. Comment discipline decides what deserves a comment and what a comment may say; only form is set here.
11
+
12
+ ## Doc descriptions
13
+
14
+ <!-- rule: doc-descriptions 1 -->
15
+
16
+ When a description leads with a verb, the verb is third-person indicative with the subject understood: "Builds the canonical payload shape", not "Build the canonical payload shape".
17
+
18
+ Existing imperative descriptions are drift, not local standard. Do not imitate them.
19
+
20
+ ## Inline comments
21
+
22
+ <!-- rule: inline-comments 1 -->
23
+
24
+ An explanatory inline comment describing a logical step is imperative, not declarative or passive: "Validate arguments", not "Validates arguments" or "Argument validation".
25
+
26
+ ## Line wrapping
27
+
28
+ <!-- rule: line-wrapping 1 -->
29
+
30
+ When an edit pushes a line of a wrapped comment past the width that its other lines keep, reflow the paragraph from that line on. A reflow changes only whitespace; make it as part of the edit, without asking.
@@ -0,0 +1,15 @@
1
+ ---
2
+ slug: williamthorsen-subagent-model-preferences
3
+ description: William Thorsen's preferences for which Claude model a subagent dispatch uses, chosen by what the subagent's task produces.
4
+ delivery: ambient
5
+ supported-harnesses: claude
6
+ version: '1'
7
+ ---
8
+
9
+ # William Thorsen's subagent-model preferences
10
+
11
+ When dispatching a subagent through the Agent tool or a workflow's `agent()` call, choose its model by what its task produces:
12
+
13
+ - A task that only searches for or locates files or code: Pass `haiku`.
14
+ - A task that only reads, runs checks, or reports, and does not write code or prose: Pass `sonnet`.
15
+ - A task that writes code or prose, including a plan, a ticket, or a message: Leave the model unset, so that the subagent runs on its declared model or the session's.
@@ -0,0 +1,22 @@
1
+ ---
2
+ slug: williamthorsen-ticketing-preferences
3
+ description: William Thorsen's preferences for how work is split across tickets, how the relationships between them are recorded, and which figures a ticket body states.
4
+ delivery: hook
5
+ version: '5'
6
+ ---
7
+
8
+ # William Thorsen's ticketing preferences
9
+
10
+ ## Splitting work across tickets
11
+
12
+ When work deserves more than one pull request, give each pull request its own ticket. When splitting a ticket into two, keep the first piece in the originating ticket. When splitting into more, make the originating ticket an umbrella.
13
+
14
+ A piece earns a ticket when it ships and can be verified on its own, not when it looks large enough to deserve one. When the count is a judgment, cut finer: Merging two tickets that turned out to be one costs an edit and a close, while splitting one that turned out to be four costs a rewrite of the original, new children, a re-cut plan, and whatever was committed against the superseded contract.
15
+
16
+ This governs work already judged to need more than one pull request. Whether work discovered mid-change becomes a ticket at all is decided first by the fold-in default in [scope-and-deferral.md](../../skills/_data/scope-and-deferral.md).
17
+
18
+ Record the relationships natively when the tracker supports them -- blockers, and parent to child -- rather than as prose in a body.
19
+
20
+ ## Counts in a ticket body
21
+
22
+ State a condition rather than a measurement: "the record covers one file and contains rejections taken at older rule versions", not "257 candidates, 8 of them stale". Admit a figure only when it defines the work: a budget, a threshold, or a value that an acceptance criterion is checked against. A count in an existing ticket that has since drifted is not a defect: Do not re-measure it, report it, or propose an edit to correct it.
@@ -0,0 +1,36 @@
1
+ ---
2
+ slug: williamthorsen-tooling-preferences
3
+ description: William Thorsen's preferences for which command-line tool an agent reaches for, how it invokes it, and how it obtains a tool or resource that is missing.
4
+ delivery: ambient
5
+ version: '3'
6
+ ---
7
+
8
+ # William Thorsen's tooling preferences
9
+
10
+ Which command-line tool to reach for, how to invoke it, and how to obtain one that is missing.
11
+
12
+ ## Searching and finding files
13
+
14
+ When searching from the shell, search file contents with `rg` and find files by name with `fd`. Both are far faster than `grep` and `find`, and over a session the difference is minutes rather than milliseconds. A harness search tool that already wraps ripgrep satisfies this rule rather than conflicting with it.
15
+
16
+ Reach for `grep` or `find` only when the faster tool is genuinely unavailable: on a machine without it, or in a portable script whose consumers may not have it.
17
+
18
+ ## Missing tools and resources
19
+
20
+ Before reporting a tool, dependency, or service as missing, exhaust the routes that do not need any action from the developer:
21
+
22
+ - Run the tool through an ephemeral runner, such as `pnpm dlx`, `npx`, `uvx`, or `go run`.
23
+ - Use a copy already present in the project, or an equivalent tool.
24
+ - Redirect a cache or temporary path out of a denied location.
25
+ - Call the service's API when the CLI is only a wrapper over it.
26
+ - Start a stopped service that the project defines, through its compose stack or its start script.
27
+
28
+ Never hand over a command that the sandbox refuses. When the resource that it reaches is within what the task was given, retry the command through the permission gate, which approves or refuses the retry. When the resource is not within the task, or when the retry is refused, ask once for the grant that clears it, propose the durable grant that removes the block for later sessions, with its tradeoff in one line (the grant widens what every later sandboxed command may reach), and run the command once the grant lands.
29
+
30
+ Ask for the resource when none of those routes works, when the missing resource is a credential or access, or when the stopped service is one that the project does not define. Name the resource and the command that will run once it arrives, and keep the task: Never restate the task as an action item for the developer. The "Handoffs" section of William Thorsen's collaboration preferences states the ladder on which this ask is the third rung. A credential or access that is already present is the task's to use only when the task's plan or the developer names the command that reads it. Never look for or use any other: It belongs to the developer.
31
+
32
+ This rule runs before any fallback that a skill names for an unavailable tool. A skill's "unavailable" means unavailable once these routes are exhausted, and the skill's fallback applies from that point.
33
+
34
+ The rule does not license any write. Acquiring a resource in a way that mutates shared state, such as installing a tool globally, restarting a service that the project does not define, minting a credential, or widening a sandbox grant, still needs the developer's authorization, and the ask is how to obtain it.
35
+
36
+ Where a `sandbox-conventions` rulebook is deployed, consult it first for a denial that misreports itself as a missing resource.
@@ -0,0 +1,90 @@
1
+ ---
2
+ slug: williamthorsen-typescript-preferences
3
+ description: 'TypeScript language mechanics, module shape, and documentation form: type safety, exports and barrels, import specifiers, type placement, and doc tags. Consult before writing or modifying TypeScript.'
4
+ delivery: [hook, skill]
5
+ version: '4'
6
+ ---
7
+
8
+ # William Thorsen's TypeScript preferences
9
+
10
+ TypeScript language mechanics, the shape of a module's public surface, and documentation form.
11
+
12
+ ## Exports
13
+
14
+ Export by name. Never use a default export: Importers invent their own names, and renames never propagate.
15
+
16
+ ## Barrels
17
+
18
+ A barrel (an `index.ts` that re-exports a directory's modules) is permitted only at a package's published entry point: a module named in the package's `exports` map, whether the root entry or a subpath. Everywhere else, an import names the defining module directly.
19
+
20
+ Importing one symbol through a barrel loads every module re-exported by the barrel.
21
+
22
+ A barrel is also permitted at a vendor boundary that lint enforces: A directory containing the sole permitted import site for an external dependency is a module boundary in the same sense as a package entry point. The permission rests on the enforcement, so a boundary not protected by a lint rule does not get a barrel.
23
+
24
+ ## Import specifiers
25
+
26
+ Write the specifier that names the file on disk: `./parse-note.ts`, not `./parse-note.js`.
27
+
28
+ This requires `allowImportingTsExtensions` and a build that rewrites extensions in output and declarations. Without both, use the `.js` form.
29
+
30
+ ## Type safety
31
+
32
+ Never use a type assertion (`as Type`, `<Type>value`): It claims a runtime guarantee that the code cannot make. When the type is not guaranteed, return `unknown` and let the caller narrow it with a type guard.
33
+
34
+ ```typescript
35
+ // ❌ Claims a type that nothing verified
36
+ function readConfig<T>(path: string): T {
37
+ return JSON.parse(fs.readFileSync(path, 'utf8')) as T;
38
+ }
39
+
40
+ // ✅ Returns what it knows; the caller narrows
41
+ function readConfig(path: string): unknown {
42
+ return JSON.parse(fs.readFileSync(path, 'utf8'));
43
+ }
44
+
45
+ function isConfig(value: unknown): value is Config {
46
+ return isObject(value) && typeof value.version === 'string';
47
+ }
48
+ ```
49
+
50
+ Two exceptions, each with a comment saying why: a TypeScript limitation in which the type is guaranteed but uninferable, such as `Object.keys()`; and test code, where precise typing of an external API would obscure the test.
51
+
52
+ Never use `any`, a non-null assertion (use a runtime assertion instead), or a generic parameter that claims a guarantee that the function cannot deliver. Model known variants as a union, and validate external data with a type guard or a schema library.
53
+
54
+ Prefer `undefined` to `null` unless serialization requires otherwise.
55
+
56
+ ## Functions
57
+
58
+ Prefer function declarations to function expressions, unless the variable is typed:
59
+
60
+ ```tsx
61
+ // ❌ Incorrect
62
+ const myFunction = () => {
63
+ /* ... */
64
+ };
65
+
66
+ // ✅ Correct
67
+ function myFunction() {
68
+ /* ... */
69
+ }
70
+
71
+ // ✅ Correct: Variable has type annotation
72
+ const MyComponent: React.FC = () => {
73
+ /* ... */
74
+ };
75
+ ```
76
+
77
+ ## Type placement
78
+
79
+ Keep types in the same file as their sole provider (component or function). This enables single imports: `import { Component, type ComponentProps } from './Component'`
80
+
81
+ **Exception:** Only extract types to shared `types.ts` when multiple providers genuinely need the same type.
82
+
83
+ ## Documentation
84
+
85
+ Omit `@param`, `@returns`, and other tags; if a parameter has a constraint that its name and type cannot express -- such as a valid range, a precondition, or mutual incompatibility with another parameter -- describe the constraint in the description.
86
+
87
+ This prohibition against `@` tags does not apply to
88
+
89
+ - symbols exported from a package's published entry point
90
+ - custom tags such as `@internal` and `@stage`