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.
- package/.meta/changelog.json +563 -0
- package/CHANGELOG.md +134 -0
- package/LICENSE +7 -0
- package/README.md +165 -1
- package/content/_partials/README.md +192 -0
- package/content/_partials/code-descriptions.md +4 -0
- package/content/_partials/code-style.md +7 -0
- package/content/_partials/comment-discipline.md +89 -0
- package/content/_partials/concision.md +3 -0
- package/content/_partials/diff-audit-checklist.md +9 -0
- package/content/_partials/file-access.md +4 -0
- package/content/_partials/live-repo-writes.md +13 -0
- package/content/_partials/plain-speech-calibration.md +66 -0
- package/content/_partials/plain-speech.md +13 -0
- package/content/_partials/prose-line-breaks.md +3 -0
- package/content/_partials/record-marker.md +1 -0
- package/content/_partials/reduced-object-relative.md +28 -0
- package/content/_partials/shell-commands.md +3 -0
- package/content/_partials/target-file-set-resolution.md +22 -0
- package/content/_partials/technical-recommendations.md +5 -0
- package/content/_partials/test-structure-audit-checklist.md +7 -0
- package/content/_partials/ticket-assessment-baseline.md +12 -0
- package/content/_partials/ticket-assessment.md +202 -0
- package/content/_partials/work-type-choice.md +13 -0
- package/content/codeassembly-content.yaml +49 -0
- package/content/collections/all.md +11 -0
- package/content/collections/atlassian.md +16 -0
- package/content/collections/recommended.md +34 -0
- package/content/collections/triage.md +77 -0
- package/content/collections/williamthorsen.md +25 -0
- package/content/guidance/README.md +22 -0
- package/content/guidance/_harnesses/claude/CLAUDE.md +6 -0
- package/content/guidance/_harnesses/rovo/AGENTS.md +5 -0
- package/content/guidance/_harnesses/rovo/codeassembly-guidance.md +4 -0
- package/content/guidance/rulebooks/accessibility-conventions.md +20 -0
- package/content/guidance/rulebooks/codeassembly-content-specification.md +161 -0
- package/content/guidance/rulebooks/command-output-conventions.md +14 -0
- package/content/guidance/rulebooks/commit-conventions.md +72 -0
- package/content/guidance/rulebooks/generated-content-policy.md +10 -0
- package/content/guidance/rulebooks/live-worktree-policy.md +18 -0
- package/content/guidance/rulebooks/readme-conventions.md +74 -0
- package/content/guidance/rulebooks/shared-data-conventions.md +14 -0
- package/content/guidance/rulebooks/shell-conventions.md +279 -0
- package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-comment-preferences.md +30 -0
- package/content/guidance/rulebooks/williamthorsen-subagent-model-preferences.md +15 -0
- package/content/guidance/rulebooks/williamthorsen-ticketing-preferences.md +22 -0
- package/content/guidance/rulebooks/williamthorsen-tooling-preferences.md +36 -0
- package/content/guidance/rulebooks/williamthorsen-typescript-preferences.md +90 -0
- package/content/guidance/rulebooks/williamthorsen-workflow-preferences.md +58 -0
- package/content/guidance/rulebooks/williamthorsen-writing-preferences.md +80 -0
- package/content/guidance/shared/AGENTS.md +43 -0
- package/content/scripts/README.md +41 -0
- package/content/scripts/describe-change.mjs +165 -0
- package/content/scripts/get-ticket-id.sh +131 -0
- package/content/scripts/manage-jira-ticket.mjs +209 -0
- package/content/scripts/resolve-frontmatter.sh +540 -0
- package/content/scripts/resolve-review-run.mjs +12 -0
- package/content/scripts/select-lede-exemplars.mjs +208 -0
- package/content/skills/_data/action-items.md +83 -0
- package/content/skills/_data/artifact-conventions.md +969 -0
- package/content/skills/_data/bitbucket-pr-access.md +89 -0
- package/content/skills/_data/branch-format.md +34 -0
- package/content/skills/_data/change-record.md +163 -0
- package/content/skills/_data/complexity-classification.md +58 -0
- package/content/skills/_data/concision.md +23 -0
- package/content/skills/_data/deployed-file-provenance.md +46 -0
- package/content/skills/_data/design-priorities.md +76 -0
- package/content/skills/_data/gh-body-file.md +30 -0
- package/content/skills/_data/git-commands.md +39 -0
- package/content/skills/_data/naming-conventions.md +50 -0
- package/content/skills/_data/pr-resolution.md +25 -0
- package/content/skills/_data/pr-source-resolution.md +36 -0
- package/content/skills/_data/recommendation-gradient.md +90 -0
- package/content/skills/_data/scope-and-deferral.md +83 -0
- package/content/skills/_data/spike-conventions.md +89 -0
- package/content/skills/_data/ticket-evaluation.md +13 -0
- package/content/skills/_data/ticket-id-extraction.md +43 -0
- package/content/skills/_data/ticket-source-resolution.md +147 -0
- package/content/skills/_data/title-templates.md +624 -0
- package/content/skills/_data/title-voice.md +17 -0
- package/content/skills/_data/work-types.json +168 -0
- package/content/skills/_partials/acceptance-criteria-scaffold.md +15 -0
- package/content/skills/_partials/action-items.md +22 -0
- package/content/skills/_partials/bitbucket-delete-both-refusal.md +3 -0
- package/content/skills/_partials/commit-title-rendering.md +14 -0
- package/content/skills/_partials/gh-body-file.md +22 -0
- package/content/skills/_partials/nested-list-indent.md +9 -0
- package/content/skills/_partials/next-steps-after-plan.md +99 -0
- package/content/skills/_partials/next-steps-after-review.md +350 -0
- package/content/skills/_partials/option-format.md +84 -0
- package/content/skills/_partials/plan-template.md +97 -0
- package/content/skills/_partials/split-launch-prompts.md +5 -0
- package/content/skills/_partials/split-ticket-compose.md +5 -0
- package/content/skills/_partials/split-ticket-create.md +3 -0
- package/content/skills/_partials/ticket-and-plan-completeness.md +33 -0
- package/content/skills/_partials/ticket-concision.md +18 -0
- package/content/skills/_partials/ticket-criteria-conventions.md +7 -0
- package/content/skills/_partials/ticket-placement.md +14 -0
- package/content/skills/_partials/ticket-skeleton-tiers.md +6 -0
- package/content/skills/_partials/ticket-skeleton.md +13 -0
- package/content/skills/add-change-record/SKILL.md +136 -0
- package/content/skills/add-test-ids/SKILL.md +51 -0
- package/content/skills/align-ticket-with-implementation/SKILL.md +115 -0
- package/content/skills/anti-patterns/SKILL.md +57 -0
- package/content/skills/assess-ticket/SKILL.md +46 -0
- package/content/skills/assess-ticket/next-steps-after-assessment.md +98 -0
- package/content/skills/brainstorming/SKILL.md +107 -0
- package/content/skills/capture-event/SKILL.md +108 -0
- package/content/skills/capture-event/capture-event.mjs +216 -0
- package/content/skills/capture-feedback/SKILL.md +71 -0
- package/content/skills/capture-lede-decision/SKILL.md +163 -0
- package/content/skills/capture-lede-decision/capture-lede-decision.mjs +231 -0
- package/content/skills/classify-complexity/SKILL.md +92 -0
- package/content/skills/collaborate/SKILL.md +86 -0
- package/content/skills/condense-branch/SKILL.md +83 -0
- package/content/skills/create-bitbucket-pr/SKILL.md +87 -0
- package/content/skills/create-commit/SKILL.md +65 -0
- package/content/skills/create-devlog/SKILL.md +108 -0
- package/content/skills/create-gh-pr/SKILL.md +106 -0
- package/content/skills/create-pr/SKILL.md +150 -0
- package/content/skills/create-ticket/SKILL.md +350 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +148 -0
- package/content/skills/design-and-plan/SKILL.md +194 -0
- package/content/skills/development-workflows/SKILL.md +41 -0
- package/content/skills/get-ticket-id/SKILL.md +67 -0
- package/content/skills/groom-backlog/SKILL.md +245 -0
- package/content/skills/groom-backlog/groom-backlog.mjs +106 -0
- package/content/skills/implement-plan/SKILL.md +164 -0
- package/content/skills/index-prototypes/SKILL.md +145 -0
- package/content/skills/index-prototypes/index-prototypes.mjs +328 -0
- package/content/skills/kb-add/SKILL.md +156 -0
- package/content/skills/kb-add/kb-add.mjs +216 -0
- package/content/skills/kb-curate/SKILL.md +117 -0
- package/content/skills/kb-curate/kb-curate.mjs +213 -0
- package/content/skills/kb-edit/SKILL.md +128 -0
- package/content/skills/kb-edit/kb-edit.mjs +219 -0
- package/content/skills/kb-retrieve/SKILL.md +100 -0
- package/content/skills/kb-retrieve/kb-retrieve.mjs +206 -0
- package/content/skills/kb-retrieve-events/SKILL.md +98 -0
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +206 -0
- package/content/skills/kb-update-events/SKILL.md +77 -0
- package/content/skills/kb-update-events/kb-update-events.mjs +215 -0
- package/content/skills/merge-bb-pr/SKILL.md +136 -0
- package/content/skills/merge-gh-pr/SKILL.md +167 -0
- package/content/skills/merge-gh-pr/merge-gh-pr.mjs +10 -0
- package/content/skills/merge-pr/SKILL.md +368 -0
- package/content/skills/migrate-feedback-memories/SKILL.md +136 -0
- package/content/skills/migrate-feedback-memories/feedback-memories.mjs +161 -0
- package/content/skills/people-report/SKILL.md +208 -0
- package/content/skills/plan/SKILL.md +87 -0
- package/content/skills/prepare-prototype-brief/SKILL.md +126 -0
- package/content/skills/pull-from-backlog/SKILL.md +83 -0
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +208 -0
- package/content/skills/refine-plan/SKILL.md +259 -0
- package/content/skills/respond-to-review/SKILL.md +292 -0
- package/content/skills/review-bb-pr/SKILL.md +161 -0
- package/content/skills/review-branch/SKILL.md +301 -0
- package/content/skills/review-criteria/SKILL.md +108 -0
- package/content/skills/review-gh-pr/SKILL.md +155 -0
- package/content/skills/review-gh-pr/select-pr-ticket.mjs +8 -0
- package/content/skills/review-permissions/SKILL.md +39 -0
- package/content/skills/review-pr/SKILL.md +123 -0
- package/content/skills/revise-comments/SKILL.md +115 -0
- package/content/skills/revise-prose/SKILL.md +197 -0
- package/content/skills/revise-prose/revise-prose.mjs +229 -0
- package/content/skills/save-artifact/SKILL.md +69 -0
- package/content/skills/save-plan/SKILL.md +55 -0
- package/content/skills/software-engineering/SKILL.md +74 -0
- package/content/skills/streamline-guidance/SKILL.md +174 -0
- package/content/skills/streamline-guidance/streamline-guidance.mjs +211 -0
- package/content/skills/summarize-change/SKILL.md +308 -0
- package/content/skills/summarize-chat/SKILL.md +100 -0
- package/content/skills/systematic-debugging/SKILL.md +308 -0
- package/content/skills/systematic-debugging/condition-based-waiting-example.ts +160 -0
- package/content/skills/systematic-debugging/condition-based-waiting.md +122 -0
- package/content/skills/systematic-debugging/defense-in-depth.md +130 -0
- package/content/skills/systematic-debugging/find-polluter.sh +68 -0
- package/content/skills/systematic-debugging/root-cause-tracing.md +185 -0
- package/content/skills/systematic-debugging/test-academic.md +16 -0
- package/content/skills/systematic-debugging/test-pressure-1.md +67 -0
- package/content/skills/systematic-debugging/test-pressure-2.md +77 -0
- package/content/skills/systematic-debugging/test-pressure-3.md +77 -0
- package/content/skills/testing-conventions/SKILL.md +168 -0
- package/content/skills/testing-conventions/mistakes.md +1 -0
- package/content/skills/typescript-testing-conventions/SKILL.md +129 -0
- package/content/skills/update-jira-ticket/SKILL.md +245 -0
- package/content/skills/update-jira-ticket/update-jira-ticket.mjs +9 -0
- package/content/skills/update-project-guidance/SKILL.md +300 -0
- package/content/skills/upgrade-dependencies/SKILL.md +139 -0
- package/content/skills/wrap-up/SKILL.md +431 -0
- package/content/subagents/_data/claude.yaml +19 -0
- package/content/subagents/_data/rovo.yaml +31 -0
- package/content/subagents/canary.md +11 -0
- package/content/subagents/entry-drafter.md +187 -0
- package/content/subagents/handoff-reviewer.md +75 -0
- package/content/subagents/plan-reviewer.md +184 -0
- package/content/subagents/plan-reviser.md +88 -0
- package/content/subagents/prose-reviser.md +130 -0
- package/content/subagents/ticket-assessor.md +139 -0
- package/package.json +70 -2
- package/schemas/preferences.v1.json +294 -0
- package/schemas/work-types.v1.json +142 -0
|
@@ -0,0 +1,69 @@
|
|
|
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
|
+
## Filename formats
|
|
12
|
+
|
|
13
|
+
### Ticket-level artifacts
|
|
14
|
+
|
|
15
|
+
```text
|
|
16
|
+
{timestamp}_{slug}_{artifact-type}.md
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
- **timestamp**: UTC time in `YYYYMMDD-HHMMSSZ` format
|
|
20
|
+
- **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.
|
|
21
|
+
- **artifact-type**: Type of artifact. See [artifact-conventions.md](../_data/artifact-conventions.md#artifact-types) for the artifact type list.
|
|
22
|
+
|
|
23
|
+
### Run directories (review workflow)
|
|
24
|
+
|
|
25
|
+
```text
|
|
26
|
+
{timestamp}_{role}_{artifact}.md
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
- **timestamp**: UTC time in `YYYYMMDD-HHMMSSZ` format
|
|
30
|
+
- **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).
|
|
31
|
+
- **artifact**: Kebab-case identifier following the same naming conventions. See [artifact-conventions.md](../_data/artifact-conventions.md#artifact-types) for the artifact type list.
|
|
32
|
+
|
|
33
|
+
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.
|
|
34
|
+
|
|
35
|
+
## Path resolution
|
|
36
|
+
|
|
37
|
+
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.
|
|
38
|
+
|
|
39
|
+
### Ticket-scoped path
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
{artifact_base_dir}/projects/{project_slug}/tickets/{ticket_id}/
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Create the directory if needed.
|
|
46
|
+
|
|
47
|
+
### Non-ticket paths
|
|
48
|
+
|
|
49
|
+
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}/`.
|
|
50
|
+
|
|
51
|
+
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).
|
|
52
|
+
|
|
53
|
+
Follow [artifact conventions](../_data/artifact-conventions.md).
|
|
54
|
+
|
|
55
|
+
## Slug generation
|
|
56
|
+
|
|
57
|
+
Create a filesystem-safe slug (for ticket-level artifacts only):
|
|
58
|
+
|
|
59
|
+
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
|
|
60
|
+
2. If explicit title provided, use it (convert to kebab-case)
|
|
61
|
+
3. Extract descriptive part from branch name after ticket ID
|
|
62
|
+
4. Analyze recent commits for work theme
|
|
63
|
+
5. Generate concise description
|
|
64
|
+
|
|
65
|
+
Format requirements, within the length bound set by [artifact-conventions.md](../_data/artifact-conventions.md#naming-conventions):
|
|
66
|
+
|
|
67
|
+
- Kebab-case (lowercase, hyphens)
|
|
68
|
+
- Filesystem-safe characters only
|
|
69
|
+
- 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 every description loads 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 / -->
|