codeassembly-guidance 0.0.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.
Files changed (219) hide show
  1. package/.meta/changelog.json +1320 -0
  2. package/CHANGELOG.md +315 -0
  3. package/LICENSE +7 -0
  4. package/README.md +195 -1
  5. package/bin/codeassembly-validate-preferences.js +18 -0
  6. package/content/_partials/README.md +192 -0
  7. package/content/_partials/code-descriptions.md +4 -0
  8. package/content/_partials/code-style.md +7 -0
  9. package/content/_partials/comment-discipline.md +89 -0
  10. package/content/_partials/concision.md +3 -0
  11. package/content/_partials/diff-audit-checklist.md +9 -0
  12. package/content/_partials/file-access.md +4 -0
  13. package/content/_partials/live-repo-writes.md +13 -0
  14. package/content/_partials/plain-speech-calibration.md +70 -0
  15. package/content/_partials/plain-speech.md +13 -0
  16. package/content/_partials/prose-line-breaks.md +3 -0
  17. package/content/_partials/record-marker.md +1 -0
  18. package/content/_partials/reduced-object-relative.md +28 -0
  19. package/content/_partials/shell-commands.md +3 -0
  20. package/content/_partials/target-file-set-resolution.md +22 -0
  21. package/content/_partials/technical-recommendations.md +6 -0
  22. package/content/_partials/test-structure-audit-checklist.md +7 -0
  23. package/content/_partials/ticket-assessment-baseline.md +12 -0
  24. package/content/_partials/ticket-assessment.md +202 -0
  25. package/content/_partials/work-type-choice.md +13 -0
  26. package/content/codeassembly-content.yaml +59 -0
  27. package/content/collections/all.md +11 -0
  28. package/content/collections/atlassian.md +17 -0
  29. package/content/collections/recommended.md +41 -0
  30. package/content/collections/triage.md +13 -0
  31. package/content/collections/williamthorsen.md +26 -0
  32. package/content/guidance/README.md +22 -0
  33. package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
  34. package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
  35. package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
  36. package/content/guidance/rulebooks/accessibility-conventions.md +38 -0
  37. package/content/guidance/rulebooks/cli-conventions.md +192 -0
  38. package/content/guidance/rulebooks/codeassembly-content-specification.md +184 -0
  39. package/content/guidance/rulebooks/command-output-conventions.md +14 -0
  40. package/content/guidance/rulebooks/commit-conventions.md +72 -0
  41. package/content/guidance/rulebooks/generated-content-policy.md +10 -0
  42. package/content/guidance/rulebooks/live-worktree-policy.md +19 -0
  43. package/content/guidance/rulebooks/readme-conventions.md +74 -0
  44. package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
  45. package/content/guidance/rulebooks/shell-conventions.md +273 -0
  46. package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
  47. package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
  48. package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +60 -0
  49. package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
  50. package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
  51. package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
  52. package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
  53. package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
  54. package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
  55. package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
  56. package/content/guidance/shared/AGENTS.md +51 -0
  57. package/content/scripts/README.md +44 -0
  58. package/content/scripts/check-branch-currency.mjs +11 -0
  59. package/content/scripts/check-prose.mjs +171 -0
  60. package/content/scripts/describe-change.mjs +165 -0
  61. package/content/scripts/get-ticket-id.sh +131 -0
  62. package/content/scripts/manage-jira-ticket.mjs +214 -0
  63. package/content/scripts/resolve-frontmatter.sh +540 -0
  64. package/content/scripts/resolve-review-run.mjs +12 -0
  65. package/content/scripts/select-lede-exemplars.mjs +208 -0
  66. package/content/scripts/validate-preferences.mjs +146 -0
  67. package/content/skills/_data/action-items.md +83 -0
  68. package/content/skills/_data/artifact-conventions.md +1001 -0
  69. package/content/skills/_data/bitbucket-pr-access.md +89 -0
  70. package/content/skills/_data/branch-currency.md +36 -0
  71. package/content/skills/_data/branch-format.md +34 -0
  72. package/content/skills/_data/change-record.md +163 -0
  73. package/content/skills/_data/complexity-classification.md +58 -0
  74. package/content/skills/_data/concision.md +23 -0
  75. package/content/skills/_data/deployed-file-provenance.md +46 -0
  76. package/content/skills/_data/design-priorities.md +76 -0
  77. package/content/skills/_data/gh-body-file.md +30 -0
  78. package/content/skills/_data/git-commands.md +39 -0
  79. package/content/skills/_data/naming-conventions.md +50 -0
  80. package/content/skills/_data/pr-resolution.md +25 -0
  81. package/content/skills/_data/pr-source-resolution.md +36 -0
  82. package/content/skills/_data/project-stage.md +32 -0
  83. package/content/skills/_data/recommendation-gradient.md +92 -0
  84. package/content/skills/_data/scope-and-deferral.md +83 -0
  85. package/content/skills/_data/spike-conventions.md +89 -0
  86. package/content/skills/_data/ticket-evaluation.md +13 -0
  87. package/content/skills/_data/ticket-id-extraction.md +43 -0
  88. package/content/skills/_data/ticket-source-resolution.md +180 -0
  89. package/content/skills/_data/title-templates.md +632 -0
  90. package/content/skills/_data/title-voice.md +17 -0
  91. package/content/skills/_data/work-types.json +168 -0
  92. package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
  93. package/content/skills/_partials/action-items.md +22 -0
  94. package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
  95. package/content/skills/_partials/commit-title-rendering.md +14 -0
  96. package/content/skills/_partials/gh-body-file.md +22 -0
  97. package/content/skills/_partials/jira-task-list-flattening.md +1 -0
  98. package/content/skills/_partials/nested-list-indent.md +9 -0
  99. package/content/skills/_partials/next-steps-after-plan.md +99 -0
  100. package/content/skills/_partials/next-steps-after-review.md +350 -0
  101. package/content/skills/_partials/option-format.md +85 -0
  102. package/content/skills/_partials/plan-template.md +97 -0
  103. package/content/skills/_partials/split-launch-prompts.md +5 -0
  104. package/content/skills/_partials/split-ticket-compose.md +5 -0
  105. package/content/skills/_partials/split-ticket-create.md +3 -0
  106. package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
  107. package/content/skills/_partials/ticket-concision.md +18 -0
  108. package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
  109. package/content/skills/_partials/ticket-placement.md +14 -0
  110. package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
  111. package/content/skills/_partials/ticket-skeleton.md +13 -0
  112. package/content/skills/add-change-record/SKILL.md +136 -0
  113. package/content/skills/add-test-ids/SKILL.md +51 -0
  114. package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
  115. package/content/skills/anti-patterns/SKILL.md +57 -0
  116. package/content/skills/assess-ticket/SKILL.md +46 -0
  117. package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
  118. package/content/skills/assess-usability/SKILL.md +96 -0
  119. package/content/skills/brainstorming/SKILL.md +107 -0
  120. package/content/skills/capture-event/SKILL.md +108 -0
  121. package/content/skills/capture-event/capture-event.mjs +216 -0
  122. package/content/skills/capture-feedback/SKILL.md +71 -0
  123. package/content/skills/capture-lede-decision/SKILL.md +163 -0
  124. package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
  125. package/content/skills/classify-complexity/SKILL.md +92 -0
  126. package/content/skills/collaborate/SKILL.md +86 -0
  127. package/content/skills/condense-branch/SKILL.md +83 -0
  128. package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
  129. package/content/skills/create-commit/SKILL.md +65 -0
  130. package/content/skills/create-devlog/SKILL.md +108 -0
  131. package/content/skills/create-gh-pr/SKILL.md +121 -0
  132. package/content/skills/create-pr/SKILL.md +150 -0
  133. package/content/skills/create-ticket/SKILL.md +395 -0
  134. package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
  135. package/content/skills/derive-session-context/derive-session-context.mjs +149 -0
  136. package/content/skills/design-and-plan/SKILL.md +197 -0
  137. package/content/skills/development-workflows/SKILL.md +41 -0
  138. package/content/skills/get-ticket-id/SKILL.md +67 -0
  139. package/content/skills/groom-backlog/SKILL.md +247 -0
  140. package/content/skills/groom-backlog/groom-backlog.mjs +108 -0
  141. package/content/skills/implement-plan/SKILL.md +168 -0
  142. package/content/skills/index-prototypes/SKILL.md +200 -0
  143. package/content/skills/index-prototypes/index-prototypes.mjs +388 -0
  144. package/content/skills/kb-add/SKILL.md +157 -0
  145. package/content/skills/kb-add/kb-add.mjs +216 -0
  146. package/content/skills/kb-curate/SKILL.md +119 -0
  147. package/content/skills/kb-curate/kb-curate.mjs +213 -0
  148. package/content/skills/kb-edit/SKILL.md +128 -0
  149. package/content/skills/kb-edit/kb-edit.mjs +219 -0
  150. package/content/skills/kb-retrieve/SKILL.md +100 -0
  151. package/content/skills/kb-retrieve/kb-retrieve.mjs +207 -0
  152. package/content/skills/kb-retrieve-events/SKILL.md +98 -0
  153. package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +207 -0
  154. package/content/skills/kb-update-events/SKILL.md +77 -0
  155. package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
  156. package/content/skills/merge-bb-pr/SKILL.md +136 -0
  157. package/content/skills/merge-gh-pr/SKILL.md +167 -0
  158. package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
  159. package/content/skills/merge-pr/SKILL.md +368 -0
  160. package/content/skills/migrate-feedback-memories/SKILL.md +137 -0
  161. package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
  162. package/content/skills/people-report/SKILL.md +208 -0
  163. package/content/skills/plan/SKILL.md +87 -0
  164. package/content/skills/prepare-prototype-brief/SKILL.md +178 -0
  165. package/content/skills/pull-from-backlog/SKILL.md +83 -0
  166. package/content/skills/pull-from-backlog/pull-from-backlog.mjs +209 -0
  167. package/content/skills/refine-plan/SKILL.md +263 -0
  168. package/content/skills/refine-prototype/SKILL.md +113 -0
  169. package/content/skills/respond-to-review/SKILL.md +292 -0
  170. package/content/skills/review-bb-pr/SKILL.md +161 -0
  171. package/content/skills/review-branch/SKILL.md +303 -0
  172. package/content/skills/review-criteria/SKILL.md +141 -0
  173. package/content/skills/review-gh-pr/SKILL.md +155 -0
  174. package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
  175. package/content/skills/review-permissions/SKILL.md +39 -0
  176. package/content/skills/review-pr/SKILL.md +123 -0
  177. package/content/skills/revise-comments/SKILL.md +148 -0
  178. package/content/skills/revise-prose/SKILL.md +197 -0
  179. package/content/skills/revise-prose/revise-prose.mjs +229 -0
  180. package/content/skills/save-artifact/SKILL.md +71 -0
  181. package/content/skills/save-plan/SKILL.md +55 -0
  182. package/content/skills/software-engineering/SKILL.md +74 -0
  183. package/content/skills/streamline-guidance/SKILL.md +174 -0
  184. package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
  185. package/content/skills/summarize-change/SKILL.md +317 -0
  186. package/content/skills/summarize-chat/SKILL.md +100 -0
  187. package/content/skills/systematic-debugging/SKILL.md +308 -0
  188. package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
  189. package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
  190. package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
  191. package/content/skills/systematic-debugging/find-polluter.sh +68 -0
  192. package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
  193. package/content/skills/systematic-debugging/test-academic.md +16 -0
  194. package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
  195. package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
  196. package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
  197. package/content/skills/testing-conventions/SKILL.md +235 -0
  198. package/content/skills/triage-spike-findings/SKILL.md +113 -0
  199. package/content/skills/triage-spike-findings/triage-spike-findings.mjs +71 -0
  200. package/content/skills/typescript-testing-conventions/SKILL.md +178 -0
  201. package/content/skills/update-jira-ticket/SKILL.md +257 -0
  202. package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
  203. package/content/skills/update-project-guidance/SKILL.md +300 -0
  204. package/content/skills/upgrade-dependencies/SKILL.md +139 -0
  205. package/content/skills/wrap-up/SKILL.md +431 -0
  206. package/content/subagents/_data/claude.yaml +25 -0
  207. package/content/subagents/_data/rovo.yaml +41 -0
  208. package/content/subagents/canary.md +12 -0
  209. package/content/subagents/disposition-challenger.md +78 -0
  210. package/content/subagents/entry-drafter.md +191 -0
  211. package/content/subagents/handoff-reviewer.md +75 -0
  212. package/content/subagents/plan-reviewer.md +184 -0
  213. package/content/subagents/plan-reviser.md +88 -0
  214. package/content/subagents/prose-reviser.md +132 -0
  215. package/content/subagents/ticket-assessor.md +142 -0
  216. package/content/subagents/usability-assessor.md +157 -0
  217. package/package.json +74 -2
  218. package/schemas/preferences.v1.json +321 -0
  219. package/schemas/work-types.v1.json +142 -0
@@ -0,0 +1,71 @@
1
+ ---
2
+ name: save-artifact
3
+ description: Save AI-generated artifacts with standardized naming and organization
4
+ user-invocable: false
5
+ ---
6
+
7
+ # Save artifact
8
+
9
+ Save AI-generated files with standardized naming conventions.
10
+
11
+ An artifact belongs to the developer's audit trail, as [artifact-conventions.md](../_data/artifact-conventions.md#purpose) states. Put instructions, a procedure, or a reference that a later session must find in the repository, or in a skill or rulebook, and not in an artifact.
12
+
13
+ ## Filename formats
14
+
15
+ ### Ticket-level artifacts
16
+
17
+ ```text
18
+ {timestamp}_{slug}_{artifact-type}.md
19
+ ```
20
+
21
+ - **timestamp**: UTC time in `YYYYMMDD-HHMMSSZ` format
22
+ - **slug**: Kebab-case descriptor of the change. See [artifact-conventions.md](../_data/artifact-conventions.md#naming-conventions) for what it is drawn from and the length bound, and [Slug generation](#slug-generation) below for how to produce one.
23
+ - **artifact-type**: Type of artifact. See [artifact-conventions.md](../_data/artifact-conventions.md#artifact-types) for the artifact type list.
24
+
25
+ ### Run directories (review workflow)
26
+
27
+ ```text
28
+ {timestamp}_{role}_{artifact}.md
29
+ ```
30
+
31
+ - **timestamp**: UTC time in `YYYYMMDD-HHMMSSZ` format
32
+ - **role**: Kebab-case identifier; hyphens are free within the name, underscores are reserved as structural separators. Each role has a `roleType`. See [artifact-conventions.md](../_data/artifact-conventions.md#run-artifacts-review-workflow) for the current role list and [roleType taxonomy](../_data/artifact-conventions.md#roletype-taxonomy).
33
+ - **artifact**: Kebab-case identifier following the same naming conventions. See [artifact-conventions.md](../_data/artifact-conventions.md#artifact-types) for the artifact type list.
34
+
35
+ Run artifacts are saved by the skills that produce them (`review-branch`, `respond-to-review`), into the ticket's active run. See [artifact-conventions.md](../_data/artifact-conventions.md#run-directories) for how the active run is identified.
36
+
37
+ ## Path resolution
38
+
39
+ Resolve the artifact directory before saving. Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `artifact_base_dir`, `project_slug`, and `ticket_id` from the manifest JSON emitted on stdout.
40
+
41
+ ### Ticket-scoped path
42
+
43
+ ```
44
+ {artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/
45
+ ```
46
+
47
+ Create the directory if needed.
48
+
49
+ ### Non-ticket paths
50
+
51
+ Read `artifact_paths` from the session-context manifest for category paths (chats, devlogs, plans). These are relative to the project directory: `{artifact_base_dir}/projects/{project_slug}/{category}/`.
52
+
53
+ Devlogs and deferred-findings artifacts use their non-ticket category paths only as a fallback: When a ticket is in session context they are written as ticket-level artifacts under `tickets/{ticket_id}/` instead. See [artifact conventions](../_data/artifact-conventions.md#non-ticket-paths) for the dual-homing rule. For frontmatter shapes, see `create-devlog/SKILL.md` (devlogs) and the deferred-findings step in `wrap-up/SKILL.md` (deferred-findings).
54
+
55
+ Follow [artifact conventions](../_data/artifact-conventions.md).
56
+
57
+ ## Slug generation
58
+
59
+ Create a filesystem-safe slug (for ticket-level artifacts only):
60
+
61
+ 1. Reuse the slug of the artifacts already in the ticket directory for this change, if any are there, unless the change's descriptor has moved
62
+ 2. If explicit title provided, use it (convert to kebab-case)
63
+ 3. Extract descriptive part from branch name after ticket ID
64
+ 4. Analyze recent commits for work theme
65
+ 5. Generate concise description
66
+
67
+ Format requirements, within the length bound set by [artifact-conventions.md](../_data/artifact-conventions.md#naming-conventions):
68
+
69
+ - Kebab-case (lowercase, hyphens)
70
+ - Filesystem-safe characters only
71
+ - No leading/trailing hyphens
@@ -0,0 +1,55 @@
1
+ ---
2
+ name: save-plan
3
+ description: Save plan from conversation context as a ticket-scoped artifact
4
+ user-invocable: true
5
+ ---
6
+
7
+ # Save plan
8
+
9
+ Save the plan from the current conversation as a ticket-scoped artifact. Useful after built-in plan mode, `plan`, or any conversation that produced a plan.
10
+
11
+ ## Process
12
+
13
+ 1. **Extract plan content** from conversation context (the most recent plan discussed or produced)
14
+
15
+ 2. **Resolve artifact path**:
16
+ - Invoke `node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs` via Bash to obtain `ticket_id`, `project_slug`, and `artifact_base_dir` from the manifest JSON emitted on stdout
17
+ - Ticket directory: `{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/`
18
+
19
+ 3. **Resolve the slug** per [artifact conventions](../_data/artifact-conventions.md#naming-conventions)
20
+
21
+ 4. **Resolve frontmatter fields**:
22
+
23
+ The frontmatter conforms to the [universal artifact frontmatter](../_data/artifact-conventions.md#universal-artifact-frontmatter) schema plus the [plan provenance](../_data/artifact-conventions.md#plan-provenance) extensions.
24
+
25
+ Run `{harness_home_dir}/scripts/resolve-frontmatter.sh --skill plan-mode --interactive true` via Bash. Prepend the output verbatim to the artifact body.
26
+
27
+ 5. **Save** as ticket-level artifact:
28
+
29
+ ```
30
+ {YYYYMMDD-HHMMSSZ}_{slug}_plan.md
31
+ ```
32
+
33
+ Example: `20260226-143000Z_oauth2-migration_plan.md`
34
+
35
+ `mkdir -p` the target directory before writing.
36
+
37
+ Follow [artifact conventions](../_data/artifact-conventions.md).
38
+
39
+ ## Completion
40
+
41
+ Report the file path, then present a ticket prompt and next steps together in a single message. Do not wait for the user's reply before showing next steps.
42
+
43
+ ```
44
+ Plan saved: {plan_path}
45
+
46
+ Would you like to create or update a ticket for this work? If so, use the `{skill:create-ticket}` skill.
47
+ ```
48
+
49
+ <HARD-GATE>
50
+ Follow the options, output format, and recommendation rules in [next-steps options](#next-steps-options) exactly. Do not improvise the options. The plan was developed in conversation with user participation; use this as recommendation context. Omit the ticket path from option lines: A ticket path is not available at completion time.
51
+ </HARD-GATE>
52
+
53
+ <!-- include: ../_partials/next-steps-after-plan.md / -->
54
+
55
+ <!-- include: ../_partials/option-format.md / -->
@@ -0,0 +1,74 @@
1
+ ---
2
+ name: software-engineering
3
+ description: Software engineering principles including SOLID, composition over inheritance, and API design
4
+ user-invocable: false
5
+ ---
6
+
7
+ # Software engineering principles
8
+
9
+ Broadly applicable software engineering principles not specific to a particular language or project.
10
+
11
+ ## General principles
12
+
13
+ Follow established software engineering best practices:
14
+
15
+ - Adhere to the single-responsibility principle
16
+ - Use dependency injection when appropriate
17
+ - Prefer composition over inheritance
18
+ - Write self-documenting code with clear naming
19
+ - Keep functions and classes small and focused
20
+ - Apply SOLID principles
21
+ - Minimize coupling between components
22
+
23
+ ## Library adoption
24
+
25
+ ### Research before implementation
26
+
27
+ - **Always investigate existing libraries before hand-rolling complex code**: Research and adopt reliable, lightweight solutions like `cli-table3` for table formatting and `chalk` for terminal colors
28
+ - **Don't write complicated functions solvable by lightweight libraries**: Use established libraries like `semver` instead of custom parsing
29
+ - **Prefer chalk for terminal colors**: Use `chalk.red()` instead of manual ANSI escape codes
30
+
31
+ ## Design evaluation
32
+
33
+ Rank design options on correctness (behavior, API quality, architectural soundness, testability, maintainability) and treat convenience considerations (effort, blast radius, consistency with existing code) as secondary. See [design priorities](../_data/design-priorities.md).
34
+
35
+ ## Component API design
36
+
37
+ ### Prefer minimal interfaces over full database types
38
+
39
+ When designing component props, create minimal interfaces that include only the data actually used by the component, rather than passing entire database entities.
40
+
41
+ **Do this:**
42
+
43
+ ```typescript
44
+ interface UserDisplayData {
45
+ name: string;
46
+ email: string;
47
+ }
48
+
49
+ const UserCard: FC<{ user: UserDisplayData }> = ({ user }) => {
50
+ // Component only depends on name and email
51
+ };
52
+ ```
53
+
54
+ **Not this:**
55
+
56
+ ```typescript
57
+ const UserCard: FC<{ user: Tables<'User'> }> = ({ user }) => {
58
+ // Component coupled to entire database schema
59
+ };
60
+ ```
61
+
62
+ **Benefits:**
63
+
64
+ - **Better encapsulation**: Component only depends on what it uses
65
+ - **Easier testing**: No need to mock entire complex objects
66
+ - **More reusable**: Can work with any data source providing required fields
67
+ - **Clearer contracts**: Interface shows exactly what data is needed
68
+ - **Reduced coupling**: Changes to unused fields don't affect component
69
+
70
+ **When to include extra fields:**
71
+
72
+ - Add fields you know will be needed soon (e.g., `id` for future actions)
73
+ - Include fields needed for debugging or error handling
74
+ - Balance between minimal and practical
@@ -0,0 +1,174 @@
1
+ ---
2
+ name: streamline-guidance
3
+ description: Reduce bloat in guidance files (skills, subagents, rulebooks, partials, AGENTS.md) in gradual steps, proposing cuts at a chosen level, applying the approved ones, and recording the review and the declined ones
4
+ user-invocable: true
5
+ ---
6
+
7
+ # Streamline guidance
8
+
9
+ Cut the bloat from guidance files without weakening what they direct. A bundled helper does the mechanical work: It resolves the files that a run may cut, reports the evidence against each candidate cut, and records each run's review and the cuts that the user declines. You make the judgment calls: what is a candidate, whether the evidence rules it out, and which candidates to propose.
10
+
11
+ The effect of a cut on agent behavior cannot be measured directly, so the level sets how much evidence a cut needs, and the lowest levels let a run take one small step at a time. Every cut is proposed before any file changes.
12
+
13
+ **Announce at start:** "Using streamline-guidance to propose {level} cuts to {the named paths}."
14
+
15
+ ## Arguments
16
+
17
+ | Argument | Description | Required |
18
+ | ----------------- | ---------------------------------------------------------------------------- | -------- |
19
+ | `<path>` | A guidance file, or a directory of them. Repeatable. | Yes |
20
+ | `--level <level>` | `cautious`, `conservative`, `moderate`, or `aggressive`. Default `moderate`. | No |
21
+
22
+ The skill does not take a `--dry-run` flag: A reply that does not name any row changes nothing.
23
+
24
+ ## Ordering with `revise-prose`
25
+
26
+ This skill decides how much the guidance says. {skill?:revise-prose} decides how its prose reads, and it never shortens text. If both are wanted on the same files, run this skill first: A cut can delete text that the sweep would otherwise polish.
27
+
28
+ ## Levels
29
+
30
+ A cut is one contiguous removal, rewording, or merge. Each level may cut everything that the level before it may. A cut's class is the lowest level that allows it.
31
+
32
+ - **`cautious`**: At most two cuts per run, from the `conservative` class, chosen as the two least likely to impair what the guidance does. Removing text that directs nothing ranks safer than rewording text that directs something.
33
+ - **`conservative`**: Text that directs nothing. Filler, hedges, intros, restated context, narration of how a rule was reached, a repeat within one body that is not reinforcement, and a rewording that directs the same thing in fewer words.
34
+ - **`moderate`** (default): The agent still receives every instruction, stated once or reported by a check that fails on violation. Overlapping rules merged, all but the strongest of several examples that teach one point, rationale that does not calibrate a judgment call, and prose restating a constraint that a validator reports with a readable error.
35
+ - **`aggressive`**: Nothing shows the text to be load-bearing. Rules that the agent follows without being told, examples in which the directive works alone and does not show an output shape, remaining rationale, and reference-only content moved behind a link.
36
+
37
+ A transitive file, one that a target includes or links to, is also read by consumers that nobody targeted. Cut it at `cautious` whatever the run's level.
38
+
39
+ ## Never cut
40
+
41
+ At any level, in any file:
42
+
43
+ - An output shape that the agent must reproduce, such as a rendered block or menu, or its skill-local reinforcement: the pointer or the inlined example placed at the step that produces the output.
44
+ - Text that a test asserts.
45
+ - Text that git history shows was added or restored to correct a failure.
46
+ - The part of a frontmatter `description` that says when to invoke the skill. The rest of a description is worth cutting, since the harness loads every description into the skill index of every session.
47
+ - Text inside a generated region, which the next deployment rewrites.
48
+
49
+ Do not edit any file outside the targets and their transitive files, except a rulebook `version`, a version pin, or a content hash that step 7 updates.
50
+
51
+ ## Process
52
+
53
+ ### 1. Resolve the files
54
+
55
+ Run from the repository root:
56
+
57
+ ```bash
58
+ node {harness_home_dir}/skills/streamline-guidance/streamline-guidance.mjs resolve {paths}
59
+ ```
60
+
61
+ The helper prints one JSON object. On failure it contains `ok: false`, an `error`, and a `message`: Report them and stop.
62
+
63
+ On success it contains:
64
+
65
+ - `targets` and `transitive`: Each file's repository-relative `file`, its source `bytes`, its `deployedBytes`, whether it is `dirty`, and its `generatedRegions` as line ranges. `deployedBytes` is a document's size once its includes are expanded, and, for a file that deploys only inside the documents that include it, its own size times the number of documents that it reaches; it is absent for a file that deploys nothing. A target named as a deployed copy contains `redirectedFrom`, and its `file` is the source. A transitive file contains `via`, the edges by which a target reaches it: `include` or `link`. A file that an earlier run reviewed contains `lastReview`: that run's `reviewedAt` date and, when it was measured, the `deployedBytes` that the run left the file at.
66
+ - `declined`: The cuts that the user declined on earlier runs whose text is still present, each with its `file`, `phrase`, and `class`.
67
+ - `rejected`: Each named path that cannot be a target, with its `reason`.
68
+
69
+ Report every rejected path and every redirect. Stop if `targets` is empty. Stop if any target or transitive file is `dirty`, and name those files: The run's commit must contain only the run's edits.
70
+
71
+ Keep the `deployedBytes` and `lastReview` of each file for the summary: A cut is worth what it removes from what an agent loads, which for a partial is its own saving times its reach.
72
+
73
+ ### 2. Compose the candidates
74
+
75
+ Read every target and transitive file whole. Compose candidates in the target files at the run's level, and in the transitive files from the `conservative` class. For each candidate, note its file, its line, its class, its `phrase` (the exact text that it removes or rewords, copied from the file), its replacement if it rewords or merges, and why it is safe at its class.
76
+
77
+ Make each `phrase` long enough to occur only once in its file, and keep it from overlapping any other candidate's phrase. A cut is applied by replacing its phrase, so a repeated or overlapping phrase cannot be applied.
78
+
79
+ Do not compose a candidate that removes or rewords a `declined` phrase in its file, or one inside a file's `generatedRegions`.
80
+
81
+ A rewording follows the plain-speech rule and the writing preferences in your guidance. A shorter sentence that breaks either is lengthened again by the next prose sweep.
82
+
83
+ ### 3. Check the candidates
84
+
85
+ Pass every candidate to `check`, at every level:
86
+
87
+ ```bash
88
+ cat <<'EOF' | node {harness_home_dir}/skills/streamline-guidance/streamline-guidance.mjs check
89
+ {"cuts":[{"file":"{file}","phrase":"{phrase}"}]}
90
+ EOF
91
+ ```
92
+
93
+ Each report repeats the candidate's `file` and `phrase` and adds two lists. Drop a candidate if either list rules it out:
94
+
95
+ - **`assertedBy`**: Test string literals that the phrase contains, each with its `file` and `line`. The helper errs toward reporting, so read the test line. Drop the candidate if the test checks guidance text for that literal; a literal that matches by accident, such as a common phrase in a test of unrelated code, does not rule it out.
96
+ - **`history`**: The commits that changed how often the phrase occurs in its file, newest first, each with its `sha`, `date`, `subject`, and `body`. Drop the candidate if a commit added or restored the phrase to correct a failure: Its subject or body names a fix, a regression, or a behavior that an agent got wrong. A commit that added the phrase as part of new guidance is not such evidence. If `history` is empty for text that `git blame` attributes to a commit, read that commit before deciding, because the phrase may have been reflowed since it was added.
97
+
98
+ Drop every candidate that touches an output shape or its skill-local reinforcement.
99
+
100
+ ### 4. Select the cuts to propose
101
+
102
+ - At `cautious`, propose at most two cuts across all files, target files first, ranked by how unlikely each is to impair what the guidance does.
103
+ - At any level, propose at most two cuts in transitive files, ranked the same way.
104
+ - Otherwise, propose every remaining candidate.
105
+
106
+ If nothing remains, report that the files do not have any cut to propose at this level, then continue at step 8.
107
+
108
+ ### 5. Present the cuts
109
+
110
+ Present one numbered table per [Cut table](#cut-table), then ask which rows to apply and which to decline, in the form `apply 1, 3; decline 2`. A row named in neither list is deferred: You do nothing with it, and a later run may propose it again.
111
+
112
+ ### 6. Apply
113
+
114
+ Apply each row named to apply with {tool:Edit}, phrase to phrase. Stop at the first edit that does not match, and report which row diverged.
115
+
116
+ ### 7. Bump versions and run the quality gate
117
+
118
+ Skip this step if the run did not apply any row.
119
+
120
+ 1. Bump the `version` of each rulebook for which a cut changed what the rulebook asks: a rulebook that a cut edited, and a rulebook that includes an edited file. Find the second kind by searching the rulebooks for an include directive that names the edited file. A `conservative` cut directs nothing, so it changes nothing that a rulebook asks.
121
+ 2. Run the project's quality gate as {skill:development-workflows} resolves it.
122
+ - If it fails only on a version pin or content hash that records a file edited by this run, apply the remedy that its failure message names: Update the pin to the version bumped above, or update the pin alone if the cuts did not change what the rulebook asks.
123
+ - If it fails on anything else that a cut caused, restore that cut's text, report the cut, and run the gate again. If the restored cut was the only cut to change what its rulebook asks, also restore that rulebook's `version`, and its pin if this step updated it.
124
+
125
+ ### 8. Record the run
126
+
127
+ Record what the run read and what the user declined, whether or not the run proposed or applied a cut: A run that proposes nothing has still reviewed the files. Pipe the fold to `record`, the only write path of `.agents/streamline-guidance.yaml`:
128
+
129
+ ```bash
130
+ cat <<'EOF' | node {harness_home_dir}/skills/streamline-guidance/streamline-guidance.mjs record
131
+ {"date":"{today}","declined":[{"file":"{file}","phrase":"{phrase}","class":"{class}"}],"reviewed":["{file}"]}
132
+ EOF
133
+ ```
134
+
135
+ `date` is today's ISO calendar date. `declined` lists each row that the user declined, its `phrase` as the text reads in the file, and is empty when the user declined none. `reviewed` names every target and every transitive file from step 1: A transitive file is read whole, so it was reviewed. `record` measures each reviewed file as it now stands, so the record states the size at which this run left it, the baseline for the growth that a later run reports.
136
+
137
+ ### 9. Commit
138
+
139
+ Commit per {skill:create-commit}, staging only the edited guidance files, any pin or version that step 7 updated, and the record. The body names each applied cut by file, class, and the text removed or reworded; when the run applied none, the commit contains the record alone.
140
+
141
+ ### 10. Emit the summary
142
+
143
+ Emit the summary per [Summary format](#summary-format). For the sizes after the run, run `resolve` again with the same paths; its `lastReview` now states this run, so take `Reviewed` and `Growth` from step 1.
144
+
145
+ ## Cut table
146
+
147
+ ```
148
+ | # | File | Line | Class | Cut | Why it is safe | Bytes |
149
+ | - | ------------------------------ | ---- | ------------ | ------------------------------------------------------ | ----------------------------------------------- | ----- |
150
+ | 1 | skills/demo/SKILL.md | 12 | conservative | remove "This section explains how the steps work." | an intro that the heading already states | 44 |
151
+ | 2 | skills/demo/SKILL.md | 31 | moderate | reword "…" → "…" | the rule at line 18 states the same instruction | 120 |
152
+ | 3 | _partials/shared.md (include) | 4 | conservative | remove "In general, " | a hedge that directs nothing | 12 |
153
+ ```
154
+
155
+ `Cut` shows `remove "…"` or `reword "…" → "…"`, abbreviated when the phrase is long. Mark a transitive file with the kind of its edge.
156
+
157
+ ## Summary format
158
+
159
+ ```
160
+ streamline-guidance summary (moderate)
161
+
162
+ | File | Reviewed | Growth | Deployed before | Deployed after | Saved |
163
+ | -------------------- | ---------- | ------ | --------------- | -------------- | ----- |
164
+ | skills/demo/SKILL.md | 2026-09-01 | +1,204 | 11,048 | 10,872 | 176 |
165
+ | _partials/shared.md | never | n/a | 2,436 | 2,400 | 36 |
166
+ | Total | | | 13,484 | 13,272 | 212 |
167
+
168
+ Applied 2, declined 1, deferred 0.
169
+ Follow-up: {skill?:revise-prose} skills/demo/SKILL.md
170
+ ```
171
+
172
+ List each target and each edited transitive file. `Reviewed` is the date of the file's `lastReview` from step 1, or `never`. `Growth` is `Deployed before` less that review's `deployedBytes`, signed, or `n/a` without both figures. A document's figure contains its partials' bytes, so a partial on a row of its own is counted in both. Name the follow-up only if a cut was applied.
173
+
174
+ <!-- include: ../_partials/action-items.md / -->