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.
- package/.meta/changelog.json +1320 -0
- package/CHANGELOG.md +315 -0
- package/LICENSE +7 -0
- package/README.md +195 -1
- package/bin/codeassembly-validate-preferences.js +18 -0
- 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 +70 -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 +6 -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 +59 -0
- package/content/collections/all.md +11 -0
- package/content/collections/atlassian.md +17 -0
- package/content/collections/recommended.md +41 -0
- package/content/collections/triage.md +13 -0
- package/content/collections/williamthorsen.md +26 -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 +38 -0
- package/content/guidance/rulebooks/cli-conventions.md +192 -0
- package/content/guidance/rulebooks/codeassembly-content-specification.md +184 -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 +19 -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 +273 -0
- package/content/guidance/rulebooks/ui-copy-conventions.md +34 -0
- package/content/guidance/rulebooks/williamthorsen-code-layout-preferences.md +102 -0
- package/content/guidance/rulebooks/williamthorsen-collaboration-preferences.md +60 -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 +51 -0
- package/content/scripts/README.md +44 -0
- package/content/scripts/check-branch-currency.mjs +11 -0
- package/content/scripts/check-prose.mjs +171 -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 +214 -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/scripts/validate-preferences.mjs +146 -0
- package/content/skills/_data/action-items.md +83 -0
- package/content/skills/_data/artifact-conventions.md +1001 -0
- package/content/skills/_data/bitbucket-pr-access.md +89 -0
- package/content/skills/_data/branch-currency.md +36 -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/project-stage.md +32 -0
- package/content/skills/_data/recommendation-gradient.md +92 -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 +180 -0
- package/content/skills/_data/title-templates.md +632 -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/jira-task-list-flattening.md +1 -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 +85 -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/assess-usability/SKILL.md +96 -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 +121 -0
- package/content/skills/create-pr/SKILL.md +150 -0
- package/content/skills/create-ticket/SKILL.md +395 -0
- package/content/skills/create-ticket/resolve-ticket-target.mjs +143 -0
- package/content/skills/derive-session-context/derive-session-context.mjs +149 -0
- package/content/skills/design-and-plan/SKILL.md +197 -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 +247 -0
- package/content/skills/groom-backlog/groom-backlog.mjs +108 -0
- package/content/skills/implement-plan/SKILL.md +168 -0
- package/content/skills/index-prototypes/SKILL.md +200 -0
- package/content/skills/index-prototypes/index-prototypes.mjs +388 -0
- package/content/skills/kb-add/SKILL.md +157 -0
- package/content/skills/kb-add/kb-add.mjs +216 -0
- package/content/skills/kb-curate/SKILL.md +119 -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 +207 -0
- package/content/skills/kb-retrieve-events/SKILL.md +98 -0
- package/content/skills/kb-retrieve-events/kb-retrieve-events.mjs +207 -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 +137 -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 +178 -0
- package/content/skills/pull-from-backlog/SKILL.md +83 -0
- package/content/skills/pull-from-backlog/pull-from-backlog.mjs +209 -0
- package/content/skills/refine-plan/SKILL.md +263 -0
- package/content/skills/refine-prototype/SKILL.md +113 -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 +303 -0
- package/content/skills/review-criteria/SKILL.md +141 -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 +148 -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 +71 -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 +317 -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 +235 -0
- package/content/skills/triage-spike-findings/SKILL.md +113 -0
- package/content/skills/triage-spike-findings/triage-spike-findings.mjs +71 -0
- package/content/skills/typescript-testing-conventions/SKILL.md +178 -0
- package/content/skills/update-jira-ticket/SKILL.md +257 -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 +25 -0
- package/content/subagents/_data/rovo.yaml +41 -0
- package/content/subagents/canary.md +12 -0
- package/content/subagents/disposition-challenger.md +78 -0
- package/content/subagents/entry-drafter.md +191 -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 +132 -0
- package/content/subagents/ticket-assessor.md +142 -0
- package/content/subagents/usability-assessor.md +157 -0
- package/package.json +74 -2
- package/schemas/preferences.v1.json +321 -0
- package/schemas/work-types.v1.json +142 -0
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
# Bitbucket pull-request access
|
|
2
|
+
|
|
3
|
+
Single access path for every skill that touches a Bitbucket pull request, whether it reads, creates, comments on, or merges one: `review-bb-pr`, `create-bitbucket-pr`, `merge-pr`, `merge-bb-pr`, and the review skills that post findings. One named tool and one field vocabulary keep them from each restating an access cascade or re-deriving the repository's coordinates.
|
|
4
|
+
|
|
5
|
+
## The tool
|
|
6
|
+
|
|
7
|
+
Every Bitbucket read and every Bitbucket write goes through the `bitbucketPullRequest` MCP tool, addressed by an `action` plus the coordinates below. A skill does not call a REST endpoint or a CLI, and it does not configure a credential: The tool manages its own connection, so a skill never reads an environment variable, a keychain entry, or a token file.
|
|
8
|
+
|
|
9
|
+
When the tool is not connected, stop with a stated reason naming it and the manual step that the caller can take instead. Do not fall back to another client; none is supported.
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
The `bitbucketPullRequest` MCP tool is not connected, and it is the only Bitbucket access path. Connect the Bitbucket MCP server and re-run, or {manual step} in the Bitbucket UI.
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Coordinates
|
|
16
|
+
|
|
17
|
+
Every action takes `workspaceId` and `repoId`, both required, both accepting a slug. Resolve them once, at the first source that yields a pair:
|
|
18
|
+
|
|
19
|
+
1. **A pull-request URL already in hand.** A URL of the form `https://bitbucket.org/{workspace}/{repo}/pull-requests/{number}` contains both slugs and the PR number. `review-bb-pr` takes this path when its `pr_id` is that URL, and `merge-pr` takes it when its PR resolution produced a stored or discovered URL per [PR source resolution](pr-source-resolution.md). An explicit `merge-pr --pr {n}` or `review-pr {n}` is a bare number and does not yield a pair, so it falls through.
|
|
20
|
+
2. **The git remote.** Otherwise take them from `git remote get-url origin`: Strip a trailing `.git`, then take the two path segments following `bitbucket.org`, which either `/` or `:` separates from the host. This accepts the HTTPS form (`https://{user}@bitbucket.org/{workspace}/{repo}.git`) and the SSH form (`git@bitbucket.org:{workspace}/{repo}.git`) alike.
|
|
21
|
+
|
|
22
|
+
The second source exists because the tool does not expose a "current repository" action and requires the pair on every call. It belongs here rather than in any skill: A skill states which source applies to it and links to this section, and never restates the parsing.
|
|
23
|
+
|
|
24
|
+
## Composing Markdown for Bitbucket
|
|
25
|
+
|
|
26
|
+
<!-- include: ../_partials/nested-list-indent.md / -->
|
|
27
|
+
|
|
28
|
+
The renderer is Python-Markdown, which is the source of the 4-space requirement: The divergence from GFM is a dialect difference rather than a defect in this client. The tool round-trips the submitted Markdown byte for byte in `description.raw`, so when a body reads correctly there and renders wrong in the browser, the fault is in the renderer.
|
|
29
|
+
|
|
30
|
+
The same renderer applies to a merge commit message, since Bitbucket's commit list renders a commit message as Markdown. [BCLOUD-19083](https://jira.atlassian.com/browse/BCLOUD-19083) records that behavior, asking for a way to switch it off after Bitbucket displayed a `#`-prefixed commit title as a heading.
|
|
31
|
+
|
|
32
|
+
## Reading a pull request
|
|
33
|
+
|
|
34
|
+
`action: "get"` with `prId` returns the Bitbucket REST pull-request object verbatim. The fields read by these skills:
|
|
35
|
+
|
|
36
|
+
| Field | Description |
|
|
37
|
+
| ----------------------------- | ------------------------------------------------------------------------------------ |
|
|
38
|
+
| `id` | PR number |
|
|
39
|
+
| `title` | PR title |
|
|
40
|
+
| `description` | PR body, as raw Markdown |
|
|
41
|
+
| `state` | `OPEN`, `MERGED`, `DECLINED`, or `SUPERSEDED` |
|
|
42
|
+
| `source.branch.name` | Head branch name |
|
|
43
|
+
| `source.repository.full_name` | Head repository as `{workspace}/{repo}`; differs from the resolved pair on a fork PR |
|
|
44
|
+
| `source.commit.hash` | Head commit hash, which Bitbucket may abbreviate (see below) |
|
|
45
|
+
| `destination.branch.name` | Base branch name |
|
|
46
|
+
| `links.html.href` | PR URL |
|
|
47
|
+
| `updated_on` | Last-updated timestamp, ISO 8601 |
|
|
48
|
+
| `merge_commit.hash` | Merge commit hash; present once `state` is `MERGED` |
|
|
49
|
+
|
|
50
|
+
Body text comes from `description` and nowhere else. `rendered.description` contains the same content as HTML, and `summary` contains a duplicate raw copy; a skill that substitutes either for `description` publishes or reviews the wrong text.
|
|
51
|
+
|
|
52
|
+
**`source.commit.hash` is not a fixed width.** Bitbucket has been observed returning it abbreviated to 12 characters, whereas `git rev-parse HEAD` returns 40. Compare on a prefix rather than on equality or on a fixed truncation: The platform's hash matches when it is a non-empty prefix of the local SHA and is at least 7 characters long. A shorter or empty hash fails the comparison rather than matching everything.
|
|
53
|
+
|
|
54
|
+
## Finding the pull request for a branch
|
|
55
|
+
|
|
56
|
+
`action: "list"` takes `state` and `q`, a Bitbucket query expression. To find the open pull request whose source is a given branch:
|
|
57
|
+
|
|
58
|
+
```
|
|
59
|
+
state: "OPEN"
|
|
60
|
+
q: 'source.branch.name = "{branch}"'
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Take the single result's `id` and `links.html.href`. [PR source resolution](pr-source-resolution.md#stored-pr-url) persists the URL, so a discovery that yielded only the id would leave the caller to construct it. More than one open pull request from one source branch is possible; when the list returns several, ask which one rather than picking the first. An empty list means that the branch does not have an open pull request.
|
|
64
|
+
|
|
65
|
+
This is the Bitbucket counterpart of `gh pr view` without an argument, which [PR source resolution](pr-source-resolution.md#runtime-resolution-path-add-change-record-review-pr-merge-pr) uses when neither an explicit argument nor a stored URL supplied the pull request.
|
|
66
|
+
|
|
67
|
+
## Merging a pull request
|
|
68
|
+
|
|
69
|
+
`action: "merge"` with `prId` takes three further parameters:
|
|
70
|
+
|
|
71
|
+
| Parameter | Description |
|
|
72
|
+
| ------------------- | --------------------------------------------------------------------- |
|
|
73
|
+
| `mergeStrategy` | One of the strategy names below |
|
|
74
|
+
| `message` | The whole merge-commit message, title and body together in one string |
|
|
75
|
+
| `closeSourceBranch` | Whether to delete the source branch on the remote after the merge |
|
|
76
|
+
|
|
77
|
+
Bitbucket Cloud offers six strategies. The three that a caller needs:
|
|
78
|
+
|
|
79
|
+
| Caller's strategy | `mergeStrategy` |
|
|
80
|
+
| ----------------- | --------------------- |
|
|
81
|
+
| `squash` | `squash` |
|
|
82
|
+
| `merge` | `merge_commit` |
|
|
83
|
+
| `rebase` | `rebase_fast_forward` |
|
|
84
|
+
|
|
85
|
+
A repository can disable any strategy, and the tool does not expose a list of the enabled ones. Do not pre-check: Pass the mapped value and report the platform's own error, which names the strategy that it refused.
|
|
86
|
+
|
|
87
|
+
`message` is a single field, unlike `gh pr merge`'s separate `--subject` and `--body`. Compose it as the title, a blank line, then the body.
|
|
88
|
+
|
|
89
|
+
Do not rely on the merge response's shape. Read the merge commit hash from a follow-up `action: "get"`, which returns `merge_commit.hash` once `state` is `MERGED`. A caller reads `state` alongside the hash, so that an absent hash under a `MERGED` state is reported as a completed merge with the hash unavailable rather than as a pull request that was not merged.
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
# Branch currency
|
|
2
|
+
|
|
3
|
+
A branch whose base is behind the remote's default branch gets designed, planned, or implemented without the changes that the default branch has gained since. Check the branch before such work starts, so that the check reveals the gap while it is still cheap to close.
|
|
4
|
+
|
|
5
|
+
## When to check
|
|
6
|
+
|
|
7
|
+
Check a branch other than the default branch, before the work starts. Skip the check on the default branch, comparing `branch_name` with `default_branch` stripped of its remote (everything after its first `/`), and on a detached HEAD, which the manifest reports as an empty `branch_name`. Read both values from the session-context manifest, never from git directly, so that the remote and the default branch follow the repository's preferences.
|
|
8
|
+
|
|
9
|
+
## Invocation
|
|
10
|
+
|
|
11
|
+
```
|
|
12
|
+
node {harness_home_dir}/scripts/check-branch-currency.mjs --base {default_branch} [--path {path}]...
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Pass one `--path` for each file or directory that the work touches, relative to the repository root, as the calling skill names them. Pass only paths that exist in the tree; a ticket that describes its area in prose does not supply any. The helper fetches the default branch, which is read-only, and prints one JSON object. It exits non-zero on a usage error, or when git fails after the fetch; act on a non-zero exit as on `fetched: false`, with the helper's stderr as the error.
|
|
16
|
+
|
|
17
|
+
## Acting on the result
|
|
18
|
+
|
|
19
|
+
**`fetched: false`.** Report in one line that the branch check did not run, with the `error`, and continue. Never report the branch as current. When the `consult-sandbox-conventions` skill is deployed, consult it before reading the error as a missing credential or an unreachable network.
|
|
20
|
+
|
|
21
|
+
**`behind: 0`.** Say nothing.
|
|
22
|
+
|
|
23
|
+
**`behind` above 0, `ahead: 0`, and `clean: true`.** The branch does not have any commits of its own or uncommitted changes, so a fast-forward loses nothing and can be undone. Run `git merge --ff-only {default_branch}` without asking, and report in one line that the branch was fast-forwarded by `behind` commits, followed by the [commit list](#commit-list). When the fast-forward fails, act on the result as in the next case.
|
|
24
|
+
|
|
25
|
+
**`behind` above 0 otherwise.** Report the gap and the [commit list](#commit-list), and ask how to proceed before the work starts, as a numbered gradient menu:
|
|
26
|
+
|
|
27
|
+
1. Bring the base in: by rebase onto `{default_branch}`, or by merging `{default_branch}` into the branch when `pushed` is true, because rebasing pushed commits would then need a force-push.
|
|
28
|
+
2. Proceed against the current base.
|
|
29
|
+
|
|
30
|
+
Recommend the first unless none of the gained commits touches the work. When `clean` is false, say that the tree has uncommitted changes, and do not run a git operation that would touch them before the developer answers.
|
|
31
|
+
|
|
32
|
+
## Commit list
|
|
33
|
+
|
|
34
|
+
Name each gained commit by its short SHA and subject. When paths were passed, name only the commits whose `touchesWork` is true, and state how many others the default branch gained; when none touches the work, say so. When paths were not passed, name the first 10 commits of `gained`, which is ordered newest first, and state the count of the rest.
|
|
35
|
+
|
|
36
|
+
The calling skill states what follows the report.
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
# Branch naming format
|
|
2
|
+
|
|
3
|
+
## Pattern
|
|
4
|
+
|
|
5
|
+
```
|
|
6
|
+
{TICKET_ID}/{DESCRIPTION}
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
## Separators
|
|
10
|
+
|
|
11
|
+
`_` and `/` are interchangeable separators in branch names. This is a branch-specific convention motivated by git worktrees: Worktree directories named after branches with `/` create unwanted directory nesting. Since descriptions use kebab-case (hyphens, never underscores), `_` is unambiguous as a structural separator.
|
|
12
|
+
|
|
13
|
+
## Segments
|
|
14
|
+
|
|
15
|
+
| Segment | Format | Notes |
|
|
16
|
+
| ------------- | ---------- | ----------------------------------------------------- |
|
|
17
|
+
| `TICKET_ID` | `ABC-123` | Jira-style ID. Always first. |
|
|
18
|
+
| `DESCRIPTION` | kebab-case | Short summary of the change. Everything after the ID. |
|
|
19
|
+
|
|
20
|
+
## Examples
|
|
21
|
+
|
|
22
|
+
```
|
|
23
|
+
MAC-123/add-user-profile
|
|
24
|
+
MAC-123_add-user-profile
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## Backward compatibility
|
|
28
|
+
|
|
29
|
+
Old-format branch names like `MAC-123/agents/feat/add-cache-layer` still parse correctly: Everything after the ticket ID is treated as freeform description. The deriver no longer populates `workspace` and `work_type`, and it drops them from an existing manifest when it recomposes that manifest.
|
|
30
|
+
|
|
31
|
+
## Related skills
|
|
32
|
+
|
|
33
|
+
- `derive-session-context`: Bundled TypeScript helper (`node {harness_home_dir}/skills/derive-session-context/derive-session-context.mjs`) that parses the branch name and composes all derived metadata (ticket ID, branch name, artifact paths, and other metadata) into one manifest, emitted on stdout and written to `.agents/{sanitized-branch}.branch-manifest.json`. Preferred when multiple metadata fields are needed.
|
|
34
|
+
- `get-ticket-id`: Extracts the ticket ID segment.
|
|
@@ -0,0 +1,163 @@
|
|
|
1
|
+
# The change record
|
|
2
|
+
|
|
3
|
+
A change's scope, type, and breaking marker are consolidated once from the change entries, and then written to every surface that needs them. This file defines the terms, states the two grammars that encode them (the `Change:` commit trailer, and the fenced `change-record` block that ends a pull-request body and, in its merge-commit form, a merge commit), states how overrides apply, and states how a merge reads the block back.
|
|
4
|
+
|
|
5
|
+
[`title-templates.md`](./title-templates.md) states the commands that consolidate, resolve, and render. This file states what they produce and how it is written down.
|
|
6
|
+
|
|
7
|
+
## Terms
|
|
8
|
+
|
|
9
|
+
| Term | Meaning |
|
|
10
|
+
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
11
|
+
| record | The values from which a title renders: `title`, `scope`, `type`, `breaking`, `ticket_ref`, and `pr_number`. |
|
|
12
|
+
| commit entry | The record that one commit subject or one `Change:` trailer declares. `consolidate-branch` reports these. |
|
|
13
|
+
| change entry | One outcome of a change: its `type`, the `scopes` that it touched, its `breaking` marker, the sentence of `text` that reports it, and an optional one-line `migration` naming the edit that a consumer makes. `entry-drafter` writes these. |
|
|
14
|
+
| consolidated record | The `scope`, `type`, and `breaking` to which a list of entries consolidates, by one ranking that serves both kinds. |
|
|
15
|
+
| overrides | The `scope`, `type`, and `breaking` that the author sets by hand, plus `title` at merge. |
|
|
16
|
+
| effective record | The consolidated record, or at merge the record resolved from the sources, with the overrides applied, plus the title and, at merge, `ticket_ref` and `pr_number`. |
|
|
17
|
+
| block | The fenced `change-record` block that ends a pull-request body. A merge commit contains its merge-commit form. It is never called "the record". |
|
|
18
|
+
|
|
19
|
+
## The record's fields
|
|
20
|
+
|
|
21
|
+
| Field | Meaning |
|
|
22
|
+
| ------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
|
|
23
|
+
| `breaking` | Whether the change breaks consumers. |
|
|
24
|
+
| `pr_number` | The pull request's number, which only a merge knows. |
|
|
25
|
+
| `scope` | The workspace to which the change belongs. A consolidated record names none when the entries consolidated into it name more than one. |
|
|
26
|
+
| `ticket_ref` | The reference to the ticket that the change serves. |
|
|
27
|
+
| `title` | The change's title, without any rendered prefix. |
|
|
28
|
+
| `type` | A work type declared in [`work-types.json`](./work-types.json). |
|
|
29
|
+
|
|
30
|
+
In the block and in the change summary's frontmatter, a field that is not determined is absent rather than empty, and `breaking` appears only as `true`. In JSON output, a field that nothing determines is `null`. The `*` scope normalizes to an absent scope and never appears in a consolidated record.
|
|
31
|
+
|
|
32
|
+
## The `Change:` trailer
|
|
33
|
+
|
|
34
|
+
A commit that stands for several commit entries records each one as a `Change:` trailer, rendered through `commit.title_format`. The trailer and the subject for which it stands are therefore the same grammar, and either reads back through the same template.
|
|
35
|
+
|
|
36
|
+
```
|
|
37
|
+
agents|fix: Condense the branch
|
|
38
|
+
|
|
39
|
+
Change: agents|feat: Add the parser
|
|
40
|
+
Change: agents|fix: Correct the guard
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
`condense-branch` writes one per commit entry when it squashes a branch, so a condensed branch stays readable. Because Git parses them as trailers, they may follow any number of body paragraphs.
|
|
44
|
+
|
|
45
|
+
**A commit with trailers contributes them in place of its subject.** Its subject renders the record to which those trailers already consolidate. Reading both would count the branch's commit entries twice.
|
|
46
|
+
|
|
47
|
+
## The `change-record` block
|
|
48
|
+
|
|
49
|
+
A pull-request body ends with a fenced block naming `change-record` as its info string. The payload is YAML, and the `render-block` subcommand of `describe-change.mjs` renders it; see [`render-block`](./title-templates.md#render-block).
|
|
50
|
+
|
|
51
|
+
````markdown
|
|
52
|
+
```change-record
|
|
53
|
+
title: Add the parser
|
|
54
|
+
overrides:
|
|
55
|
+
type: sec
|
|
56
|
+
breaking: true
|
|
57
|
+
entries_commit: e5029924
|
|
58
|
+
entries:
|
|
59
|
+
- type: feat
|
|
60
|
+
scopes: [agents, kb]
|
|
61
|
+
text: Adds the store-qualified wikilink `[[store:Note title]]`, which `kb check` resolves against the named store.
|
|
62
|
+
- type: drop
|
|
63
|
+
scopes: [kb]
|
|
64
|
+
breaking: true
|
|
65
|
+
text: Removes the `kb find` alias of `kb search`.
|
|
66
|
+
migration: Replace `kb find` with `kb search`, which exits nonzero when nothing matches.
|
|
67
|
+
```
|
|
68
|
+
````
|
|
69
|
+
|
|
70
|
+
| Key | Meaning |
|
|
71
|
+
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
72
|
+
| `title` | The change summary's title. Required. |
|
|
73
|
+
| `overrides` | The `scope`, `type`, or `breaking` that the author set by hand. Absent when the author set none. `breaking` appears only as `true`. |
|
|
74
|
+
| `entries_commit` | The short SHA of the commit at which the change entries were derived. Absent when the block does not record any entries. |
|
|
75
|
+
| `entries` | The change entries, in the order that the drafter returned them. Absent when there is none. Each renders `type`, `scopes` in flow form, `breaking` only when it is `true`, `text`, and `migration` when the entry has one. |
|
|
76
|
+
|
|
77
|
+
The payload is YAML rather than a surface template because `overrides` and `entries` nest, and a template renders one flat line. Nesting also leaves room for the block to gain structured keys, such as a grammar version or a ticket reference. Its inverse is a YAML parse rather than a compiled pattern, so this pair needs none of the round-trip verification required by the title grammar.
|
|
78
|
+
|
|
79
|
+
**The scalars precede `entries`** so that the bulky list does not separate the title from the overrides.
|
|
80
|
+
|
|
81
|
+
**The block records the change entries as data**, which is how a reader downstream of the merge gets them without parsing them back out of the rendered `## Details` prose. The change summary's `changes` frontmatter field is a different list: It contains the commit entries, which record what the branch's commits declared.
|
|
82
|
+
|
|
83
|
+
**The block is the body's last element.** A reader takes the last `change-record` fence in the body, and the merge body that `resolve-merge` composes from the pull request excludes every block.
|
|
84
|
+
|
|
85
|
+
## The merge-commit form
|
|
86
|
+
|
|
87
|
+
A squash merge publishes the block's change entries below the lede, in a reduced form of the block that release-kit reads from the merge commit. `resolve-merge` renders it and reports it in `merge_block`, separate from the merge body; see [`resolve-merge`](./title-templates.md#resolve-merge).
|
|
88
|
+
|
|
89
|
+
````markdown
|
|
90
|
+
```change-record
|
|
91
|
+
pr_number: 470
|
|
92
|
+
ticket_ref: "#466"
|
|
93
|
+
entries:
|
|
94
|
+
- type: feat
|
|
95
|
+
scopes: [agents, kb]
|
|
96
|
+
text: Adds the store-qualified wikilink `[[store:Note title]]`, which `kb check` resolves against the named store.
|
|
97
|
+
- type: drop
|
|
98
|
+
scopes: [kb]
|
|
99
|
+
breaking: true
|
|
100
|
+
text: Removes the `kb find` alias of `kb search`.
|
|
101
|
+
migration: Replace `kb find` with `kb search`, which exits nonzero when nothing matches.
|
|
102
|
+
```
|
|
103
|
+
````
|
|
104
|
+
|
|
105
|
+
| Key | Meaning |
|
|
106
|
+
| ------------ | ---------------------------------------------------------------------------------------------------------- |
|
|
107
|
+
| `pr_number` | The pull request's number, as a YAML integer. |
|
|
108
|
+
| `ticket_ref` | The effective record's ticket reference. Absent when the merge has none. |
|
|
109
|
+
| `entries` | The change entries that the pull request's block records, in its order, each rendered as it renders there. |
|
|
110
|
+
|
|
111
|
+
`title`, `overrides`, and `entries_commit` are left out: The merge title already renders the effective record, and the rest served only to resolve it.
|
|
112
|
+
|
|
113
|
+
**A merge without a change entry does not write a block**, since a block without entries tells release-kit nothing. That is the case when the pull request's block is absent, is malformed, or does not record an entry, and the merge body is then the lede alone.
|
|
114
|
+
|
|
115
|
+
**The form is read under release-kit's rules**, which are stricter than the pull-request form's: Any defect makes the whole block malformed, release-kit does not salvage any entry from a defective list, and `pr_number` must be a positive integer. Before merging, `merge-pr` reads the approved body back through the `check-merge-body` subcommand and refuses to merge when the block is malformed or records a different number of entries than `resolve-merge` rendered; see [`check-merge-body`](./title-templates.md#check-merge-body).
|
|
116
|
+
|
|
117
|
+
## The effective record
|
|
118
|
+
|
|
119
|
+
The overrides apply to the consolidated record one field at a time, and a field without an override keeps the consolidated record's value:
|
|
120
|
+
|
|
121
|
+
- A `scope` override replaces the scope. A scope override of `*` is recorded as given, and it leaves the effective record without a scope.
|
|
122
|
+
- A `type` override replaces the type and keeps the breaking marker.
|
|
123
|
+
- A `breaking` override sets the marker in the direction that it names. A block or a change summary records the override only as `true`, so there it can add the marker but never remove it. A merge's breaking override can also remove it.
|
|
124
|
+
|
|
125
|
+
An override is kept as the author set it, even if it equals the consolidated record. The consolidated record is re-derived whenever the branch moves, and the override has to outlast that.
|
|
126
|
+
|
|
127
|
+
The `resolve-effective-record` subcommand of `describe-change.mjs` applies this rule to a change summary's fields and reports the effective record; see [`resolve-effective-record`](./title-templates.md#resolve-effective-record). `resolve-merge` and `capture-lede-decision` apply the same rule.
|
|
128
|
+
|
|
129
|
+
## Where the record is written
|
|
130
|
+
|
|
131
|
+
| Surface | What it contains |
|
|
132
|
+
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
133
|
+
| Change-summary frontmatter | `title`, the consolidated record's `scope`, `type`, and `breaking`, `changes`, `ticket_type`, and the override fields |
|
|
134
|
+
| Condensed commit message | A subject rendered from the consolidated record, and one `Change:` trailer per commit entry |
|
|
135
|
+
| Merge commit | The lede, then the merge-commit form of the block when the pull request's block records a change entry |
|
|
136
|
+
| Pull-request body | `Closes`, then the block as the final block, copied from the change summary's body |
|
|
137
|
+
| Pull-request labels | Every type and scope that the effective record or an entry names, mapped through `.meta/label-map.json`, plus `breaking` when either is breaking; see [`resolve-labels`](./title-templates.md#resolve-labels) |
|
|
138
|
+
|
|
139
|
+
[Artifact conventions](./artifact-conventions.md#change-summary-frontmatter) specifies the change-summary fields.
|
|
140
|
+
|
|
141
|
+
## Where the record is read
|
|
142
|
+
|
|
143
|
+
`merge-pr` reads the block when it merges, through the `resolve-merge` subcommand of `describe-change.mjs` (see [`resolve-merge`](./title-templates.md#resolve-merge)), and reads a record consolidated afresh from the commits up to the pull request's head commit, on which a merge falls back when the block does not record any entries to rank. The run reports what each source names and attributes each field of the effective record to the source that supplied it, under the names that [`resolve-merge`](./title-templates.md#resolve-merge) lists.
|
|
144
|
+
|
|
145
|
+
**The body's last `change-record` block is the one read.** It is malformed when it never closes, when its payload is not a YAML mapping, when `title` is missing, empty, or not a string, when `overrides` is not a mapping, and when a declared field has the wrong type. A malformed block is reported as `malformed-block` and resolved as though it were absent. A key that the grammar does not declare is ignored, and a declared key whose value is null reads as absent.
|
|
146
|
+
|
|
147
|
+
**A defective `entries` list is the one exception to that rule.** The list is defective when it is not a list, when an item is not a mapping, when an item's `type` or `text` is missing, blank, or not a string, when its `breaking` is not a boolean, when its `scopes` is not a list of strings, or when its `migration` is not a string or spans more than one line; a non-string `entries_commit` reads the same way, since the commit records a claim about the entries. The block reads with its entries absent, its defect reported as `malformed-entries`, and its title and overrides still in use; its base record resolves as for a block that does not record any entries. Every other field keeps the all-or-nothing rule.
|
|
148
|
+
|
|
149
|
+
**The block's entries are fresh** when the block records some, records the commit at which they were derived, and the pull request's head starts with that commit. The comparison is a prefix test rather than an equality, since the block records a short SHA and the pull request reports a full one, and it ignores case. Entries recorded without a derivation commit are stale, since nothing establishes when they were read. A block whose entries are present and not fresh raises `stale-entries`, which names the derivation commit, `null` when the block records none, and the head against which it was compared.
|
|
150
|
+
|
|
151
|
+
**With entries in the block**, `resolve-merge` ranks them into a record by the rule that [`consolidate-entries`](./title-templates.md#consolidate-entries) applies, and that record stands whether or not the entries are fresh; `stale-entries` is the warning when they are not. The scopes of the change entries come from the paths that each entry touched, which the commit subjects only approximate. Every field of the record is attributed to `block`.
|
|
152
|
+
|
|
153
|
+
The block's overrides then apply to that record, as [The effective record](#the-effective-record) states, and each field that they set is attributed to `block_overrides`.
|
|
154
|
+
|
|
155
|
+
**A merge does not re-derive the block's entries.** Commits pushed after the body was composed are already out of scope at merge, so staleness is reported and the merge proceeds. A body that does not contain a block may gain one through `add-change-record` before the merge resolves; a block that is already written is never replaced, whether it reads, is malformed, or does not record an entry.
|
|
156
|
+
|
|
157
|
+
**Without entries to rank**, the labels stand in for them. This covers a body that does not contain a block, which raises `absent-block` so that a gate can report that the entries are missing rather than empty; a block that cannot be read, which raises `malformed-block` instead; and a readable block that does not record any entries or whose entries are malformed. A readable block's overrides still apply to the record chosen here, attributed to `block_overrides`. The type and its breaking marker come together, from the labels if exactly one type label resolves and otherwise from the commits. A marker never pairs with a type from the other source. The scope comes from its label if exactly one resolves, and otherwise from the commits. The breaking label is the literal `breaking`. Each field is attributed to `labels` or `commits` according to its source, so a type from the labels and a scope from the commits are reported as such.
|
|
158
|
+
|
|
159
|
+
**The merge's own overrides apply last** and outrank the block's, each on its own field, as [The effective record](#the-effective-record) states. Each field that they set is attributed to `flags`.
|
|
160
|
+
|
|
161
|
+
**The pull-request title is read whether or not the merge overrides the title.** Its prefix is compared with the effective record, and a `pr-title-divergence` notice names the fields on which they differ. A title that does not invert through `pr.title_format` raises `pr-title-unparsed`.
|
|
162
|
+
|
|
163
|
+
**The effective record must name a declared type and satisfy that type's breaking policy.** Otherwise the merge is not offered for approval until the author overrides it; nothing is normalized.
|
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# Complexity classification
|
|
2
|
+
|
|
3
|
+
Classify the complexity of a task, finding, or change to determine how it should be handled.
|
|
4
|
+
|
|
5
|
+
## Levels
|
|
6
|
+
|
|
7
|
+
| Level | Label | Characteristics |
|
|
8
|
+
| ----- | ----------------- | ----------------------------------------------------------------------------------------------------------------- |
|
|
9
|
+
| 1 | **Trivial** | Single-line or purely mechanical. No judgment needed. The fix is obvious from the description alone. |
|
|
10
|
+
| 2 | **Mechanical** | Follows an obvious pattern. Single module, no API or behavioral changes. A competent agent's first pass suffices. |
|
|
11
|
+
| 3 | **Involved** | Requires understanding context. Touches multiple files or modules. May involve design decisions. |
|
|
12
|
+
| 4 | **Architectural** | Cross-cutting concerns, new patterns, dependency boundary changes, or far-reaching consequences. |
|
|
13
|
+
|
|
14
|
+
### Level 1: Trivial
|
|
15
|
+
|
|
16
|
+
- Remove unused import
|
|
17
|
+
- Fix typo in error message or variable name
|
|
18
|
+
- Add missing return type that the compiler can infer
|
|
19
|
+
- Delete dead code already flagged by a linter
|
|
20
|
+
|
|
21
|
+
### Level 2: Mechanical
|
|
22
|
+
|
|
23
|
+
- Rename a local function or variable across its usages within a single module
|
|
24
|
+
- Add a missing test case that follows an existing test pattern
|
|
25
|
+
- Extract a repeated literal into a named constant
|
|
26
|
+
- Update a reference path after a file was moved
|
|
27
|
+
|
|
28
|
+
### Level 3: Involved
|
|
29
|
+
|
|
30
|
+
- Refactor retry logic to use a shared utility
|
|
31
|
+
- Add error handling for a new edge case that requires understanding the call chain
|
|
32
|
+
- Modify a data structure shared between modules
|
|
33
|
+
- Implement a feature that follows an established pattern but spans multiple files
|
|
34
|
+
|
|
35
|
+
### Level 4: Architectural
|
|
36
|
+
|
|
37
|
+
- Introduce a new subsystem or module boundary
|
|
38
|
+
- Change how modules communicate (new interfaces, events, or protocols)
|
|
39
|
+
- Modify dependency boundaries (add/remove/replace libraries)
|
|
40
|
+
- Restructure control flow or state management across components
|
|
41
|
+
|
|
42
|
+
## Consumer levels
|
|
43
|
+
|
|
44
|
+
Each consuming skill defines which complexity levels qualify for its "simple enough" decision against this rubric.
|
|
45
|
+
|
|
46
|
+
| Consumer | Levels | Decision |
|
|
47
|
+
| --------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
48
|
+
| `wrap-up` drive-by pass | 1–2 | Apply immediately on the current branch; skip ticket creation |
|
|
49
|
+
| `design-and-plan` / `plan` handoff pass | 1–2 | Skip the handoff pass; the session reports the skip in one line that names the level, and saves the artifacts |
|
|
50
|
+
| `next-steps-after-plan` | 1–2 | Recommend "Implement". When a review pass would catch nothing meaningful (e.g., a typo or unused-import removal), note on the option that the review can be skipped at `implement-plan`'s closing menu. |
|
|
51
|
+
| `implement-plan` closing menu | 1–2 | Recommend "Create PR without review"; the realized diff is trivial enough that a review pass would catch nothing meaningful |
|
|
52
|
+
| `next-steps-after-review` | n/a | Trivial findings usually name a single change, for which the skill recommends "Implement directly and commit"; the recommendation depends on the finding's shape rather than on the level. |
|
|
53
|
+
|
|
54
|
+
When characteristics span two levels, prefer the higher level.
|
|
55
|
+
|
|
56
|
+
Consumers above level 2 should use the level descriptions to inform their own routing logic rather than relying solely on this table.
|
|
57
|
+
|
|
58
|
+
The complexity rubric and the [scope-and-deferral](scope-and-deferral.md) model compose: Complexity decides the routing (which skill picks the work up next), and scope-and-deferral decides whether the work needs its own ticket at all.
|
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
# Concision
|
|
2
|
+
|
|
3
|
+
Detail adds value up to a peak, then wastes the reader's attention: Past the peak, added detail hides the signal that it was meant to convey. Add detail only while it adds signal. Weigh each sentence by how much signal it adds, not by its length.
|
|
4
|
+
|
|
5
|
+
## Compose tight the first time
|
|
6
|
+
|
|
7
|
+
Compose from a skeleton, not a full draft that you trim later. Start with the one sentence without which the reader cannot act, then add only what changes what they do next. If you find yourself trimming, you started too loose.
|
|
8
|
+
|
|
9
|
+
## Proportionality
|
|
10
|
+
|
|
11
|
+
A load-bearing decision is worth elaborating; a routine one is worth a clause. A decision is load-bearing if the reader could act differently depending on it.
|
|
12
|
+
|
|
13
|
+
## What to cut
|
|
14
|
+
|
|
15
|
+
Intros, hedging, restated context, exhaustive enumeration. Process narration (how the work or decision was reached) when only the conclusion serves the reader.
|
|
16
|
+
|
|
17
|
+
## Self-test
|
|
18
|
+
|
|
19
|
+
For each sentence, ask: Would removing it change what the reader does, or must know to act? If not, cut it. Run this before presenting, not after a reader complains.
|
|
20
|
+
|
|
21
|
+
## Cut noise, never signal
|
|
22
|
+
|
|
23
|
+
This overrides the cut-list and self-test: Never drop a decision, constraint, or actionable fact for brevity, even when applying them would remove it. Detail is moved elsewhere, not omitted: Each artifact's doctrine names where cut detail belongs.
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# Deployed-file provenance
|
|
2
|
+
|
|
3
|
+
How to tell whether a file was deployed by CodeAssembly, where its source is, and how to get a change into it.
|
|
4
|
+
|
|
5
|
+
## Detection
|
|
6
|
+
|
|
7
|
+
A file is deployed when any of the following holds.
|
|
8
|
+
|
|
9
|
+
**It contains a provenance marker.** `install` writes three comment lines into each harness guidance file, headed by one of:
|
|
10
|
+
|
|
11
|
+
- `# GENERATED FILE - Do not edit this file.`, immediately after the opening `---`, when the file has frontmatter
|
|
12
|
+
- `<!-- GENERATED FILE - Do not edit this file. -->`, at the top, when it does not
|
|
13
|
+
|
|
14
|
+
**It contains an ownership marker.** `sync` writes one line, placed after the frontmatter's closing `---` rather than at the top of the file:
|
|
15
|
+
|
|
16
|
+
- `<!-- codeassembly-skill:{slug} -->` in a skill's `SKILL.md`
|
|
17
|
+
- `<!-- codeassembly-subagent:{slug} -->` in a subagent's file
|
|
18
|
+
- `<!-- codeassembly-rulebook:{slug} -->` in a rulebook delivered as a skill
|
|
19
|
+
|
|
20
|
+
In a rulebook that declares a version, the `<!-- codeassembly-rulebook:{slug} -->` marker is followed by `<!-- rulebook-version: {version} -->`, so that a reader can name the version of the guidance in front of them.
|
|
21
|
+
|
|
22
|
+
**It is under a harness's `skills/` tree.** `sync` populates that tree and marks only part of what it leaves there: A skill's root `SKILL.md` contains an ownership marker while its nested Markdown and bundled scripts contain none, and each declared source's support entries, such as its `_data/` tree, are under `_sources/<name>/`. The one thing there that is not deployed is a skill added by hand, whose `SKILL.md` does not contain an ownership marker.
|
|
23
|
+
|
|
24
|
+
**It is in a harness's `scripts/` directory.** `install` copies those files verbatim and marks none of them, whatever the extension.
|
|
25
|
+
|
|
26
|
+
A region can be generated inside a file that is not. `sync` rewrites everything between `<!-- codeassembly-ambient:start -->` and `<!-- codeassembly-ambient:end -->` on every run, and in a project that region is inside an otherwise hand-authored guidance file. Inside it, each rulebook's block runs from `<!-- rulebook:{slug} -->` to `<!-- /rulebook:{slug} -->`, with `<!-- rulebook-version: {version} -->` directly below the open marker when the rulebook declares a version. A guidance-hook fill spliced into a skill or subagent body contains the same block.
|
|
27
|
+
|
|
28
|
+
One deployed file has neither a marker nor a marked artifact around it: `install --link` writes a symlink rather than a copy. Its target is a build output under `dist/`, so an edit there survives until the next build and no longer.
|
|
29
|
+
|
|
30
|
+
## Finding the source
|
|
31
|
+
|
|
32
|
+
An `install`-deployed file's marker contains a `Source:` line naming the file from which it was built: the path within the source, the source's name, and the source directory. A support entry under `_sources/<name>/` comes from the `skills/` directory of the declared source of that name. A script does not have a marker: A shell script's source is the matching file under `scripts/` in the declaring source, while a `.mjs` anywhere is a build output rather than a checked-in file, and its source is the `entry` that the `helpers:` list in its content root's `codeassembly-content.yaml` maps to it.
|
|
33
|
+
|
|
34
|
+
A `sync`-deployed artifact does not have such a line either. Read the resolution report from the dry run for the file's domain: `codeassembly sync --dry-run` for a file under a project's harness directory, and `codeassembly sync --global --dry-run` for one under the home directory. A dry run of the wrong domain lists other artifacts, or none at all when that domain declares nothing. The report names each deployed artifact's origin:
|
|
35
|
+
|
|
36
|
+
- `← source "<name>"` is the `sources:` or `packages:` entry of that name in the `codeassembly.yaml` scope chain. The CodeAssembly library is conventionally declared as the `sources:` entry `codeassembly`, whose `path` names a clone's `packages/guidance/content/`.
|
|
37
|
+
|
|
38
|
+
An ambient region's source is the rulebooks named by its `<!-- rulebook:{slug} -->` blocks, each resolved through the same report.
|
|
39
|
+
|
|
40
|
+
## Getting a change in
|
|
41
|
+
|
|
42
|
+
1. Edit the source file, and open a pull request against the repository that owns it. For a deployed `.mjs` that is the bundler entry named above; the `.mjs` beside it in the source tree is generated and gitignored.
|
|
43
|
+
2. After merge, redeploy with the command that deployed it:
|
|
44
|
+
- `codeassembly install` for a harness guidance file or a script
|
|
45
|
+
- `codeassembly sync` for a file under a project's harness directory
|
|
46
|
+
- `codeassembly sync --global` for one under the home directory
|
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
# Design priorities
|
|
2
|
+
|
|
3
|
+
Prioritize the right decision over the most convenient one.
|
|
4
|
+
|
|
5
|
+
## The principle
|
|
6
|
+
|
|
7
|
+
Design options have two kinds of properties.
|
|
8
|
+
|
|
9
|
+
**Correctness** (what makes the design right):
|
|
10
|
+
|
|
11
|
+
- Behavioral correctness: Does it produce the right results across the cases that matter? The project's declared stage sets which cases matter; see [project stage](project-stage.md).
|
|
12
|
+
- API quality: Clear contracts, expressive interfaces, sensible boundaries
|
|
13
|
+
- Architectural soundness: Modularity, separation of concerns, single responsibility, composability, SOLID
|
|
14
|
+
- Testability: The design can be verified in isolation
|
|
15
|
+
- Maintainability: The design holds up over time; clarity and evolvability under future requirements
|
|
16
|
+
|
|
17
|
+
**Convenience** (what makes the change easy now):
|
|
18
|
+
|
|
19
|
+
- Level of effort: Diff size, lines changed, files touched
|
|
20
|
+
- Blast radius: Downstream callers, tests, or consumers requiring updates
|
|
21
|
+
- Consistency with existing code: Matching pre-existing patterns to avoid divergence
|
|
22
|
+
- Scope minimization: Leaving adjacent issues unaddressed because they weren't in the ticket
|
|
23
|
+
|
|
24
|
+
Rank options on correctness. Convenience is secondary: a tiebreaker among correctness-equivalent options at most. If one option is correctness-superior, recommend it even when it is more work, touches more files, or diverges from surrounding code.
|
|
25
|
+
|
|
26
|
+
## Why
|
|
27
|
+
|
|
28
|
+
Correctness determines what it costs to live with the system over its remaining life. A clean design can be evolved; a wrong one accumulates patches around its wrongness. Convenience saves effort only once, at the moment of change.
|
|
29
|
+
|
|
30
|
+
## Before / after
|
|
31
|
+
|
|
32
|
+
A typical decision: A feature needs a new validation step. Two options:
|
|
33
|
+
|
|
34
|
+
A. Add the validation as a method on the existing god-class that already owns adjacent concerns.
|
|
35
|
+
B. Extract a small dedicated module with a narrow interface and inject it.
|
|
36
|
+
|
|
37
|
+
**Convenience-led ranking** (don't do this):
|
|
38
|
+
|
|
39
|
+
```
|
|
40
|
+
1. ■■■ Extend the god-class:
|
|
41
|
+
- ➕ minimal diff
|
|
42
|
+
- ➕ no new files
|
|
43
|
+
- ➕ matches surrounding code
|
|
44
|
+
2. ■□□ Extract a module:
|
|
45
|
+
- ➖ more files
|
|
46
|
+
- ➖ touches injection sites
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
**Correctness-led ranking** (do this):
|
|
50
|
+
|
|
51
|
+
```
|
|
52
|
+
1. ■■■ Extract a module:
|
|
53
|
+
- ➕ narrow interface
|
|
54
|
+
- ➕ testable in isolation
|
|
55
|
+
- ➕ untangles concerns that the god-class already conflates
|
|
56
|
+
2. □□□ Extend the god-class:
|
|
57
|
+
- ➖ deepens an existing SRP violation; convenience gain is one-off, complexity cost compounds
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
The factual lists about each option are similar; the **ranking** flips because the criteria changed.
|
|
61
|
+
|
|
62
|
+
## Designing as if from the beginning
|
|
63
|
+
|
|
64
|
+
When designing a change, ask: _How would we have written this if the new behavior had been there from the start?_ Aim the design at that target.
|
|
65
|
+
|
|
66
|
+
Three patterns signal a design that hasn't reached it:
|
|
67
|
+
|
|
68
|
+
- **Workarounds**: Changing surrounding code to accommodate a fix instead of changing the code that's wrong.
|
|
69
|
+
- **Carve-outs**: Special cases or conditional branches that exist because the change couldn't be integrated cleanly, not because the cases are genuinely distinct.
|
|
70
|
+
- **Bolt-ons**: New modules or extension points appended alongside existing structure when the existing structure should have evolved to absorb the change.
|
|
71
|
+
|
|
72
|
+
A fresh codebase wouldn't have these shapes; their presence means the change was attached to the system rather than integrated into it. Reaching the target may require touching code outside the ticket's literal scope: renaming, restructuring, generalizing. That cost is real but bounded; the cost of keeping a poorly integrated change compounds.
|
|
73
|
+
|
|
74
|
+
## Reconciliation
|
|
75
|
+
|
|
76
|
+
These rules reinforce "push back on questionable legacy": the guidance to examine, not preserve, carve-outs labelled "for backward compatibility" or "matches existing convention" when normalization would not break any concrete consumer.
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
# gh body file
|
|
2
|
+
|
|
3
|
+
Pattern for passing composed content to a CLI without sending it through bash.
|
|
4
|
+
|
|
5
|
+
The contract comes first; the reasoning behind it follows. Skills that compose a body inline the contract rather than linking to it, so they consult this file only for the reasoning.
|
|
6
|
+
|
|
7
|
+
<!-- include: ../_partials/gh-body-file.md / -->
|
|
8
|
+
|
|
9
|
+
## Why a file rather than the shell
|
|
10
|
+
|
|
11
|
+
Historically, agents authored bodies via single-quoted bash heredocs:
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
gh issue create --body "$(cat <<'EOF'
|
|
15
|
+
...
|
|
16
|
+
EOF
|
|
17
|
+
)"
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Although a `<<'EOF'` heredoc does not perform any expansion and backticks do not need escaping, agents reflexively inserted `\` before every backtick, a habit brought over from double-quoted strings. GitHub rendered the backslashes literally, producing broken code spans (`` \`foo\` ``) and fences (``\`\`\`ts``). The bug recurred across creation flows in multiple repositories.
|
|
21
|
+
|
|
22
|
+
Writing the body through the {tool:Write} tool removes bash from the path entirely. The path does not pass through any shell context in which escaping could seem necessary, so the class of bug cannot arise. See codeassembly#442 for the originating incident.
|
|
23
|
+
|
|
24
|
+
## Why the path is re-stated at every call
|
|
25
|
+
|
|
26
|
+
The pattern once prescribed a `$TMPDIR`-relative path and told the caller to keep it in a `body_path` variable that later calls would reuse. Neither works in an agent harness. `$TMPDIR` alternates between the sandbox value and the launchd per-user value between Bash invocations, and a shell variable does not outlive one at all. A `gh` call made with the variable unset published GitHub's default body onto a squash commit that could not be amended on a protected default branch. See codeassembly#1599.
|
|
27
|
+
|
|
28
|
+
## Cleanup
|
|
29
|
+
|
|
30
|
+
None is required. Each call creates its own directory, so a file left in one collides with nothing and is readable only by the user who wrote it.
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# Useful git commands
|
|
2
|
+
|
|
3
|
+
## Amend the message of a previous commit
|
|
4
|
+
|
|
5
|
+
To amend the message of a commit that is in the current history but not HEAD:
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
ORIGINAL_BRANCH=$(git branch --show-current); \
|
|
9
|
+
TEMP_BRANCH=${ORIGINAL_BRANCH}-temp; \
|
|
10
|
+
git checkout -b $TEMP_BRANCH; \
|
|
11
|
+
git reset --hard <commit-hash>; \
|
|
12
|
+
git commit --amend --no-gpg-sign --no-verify -m "Your new commit message"; \
|
|
13
|
+
git checkout $ORIGINAL_BRANCH; \
|
|
14
|
+
git rebase --onto $TEMP_BRANCH <commit-hash> $ORIGINAL_BRANCH; \
|
|
15
|
+
git branch -D $TEMP_BRANCH
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
Because AI agents typically execute commands in separate shells, and would lose the variable assignments,
|
|
19
|
+
the above steps are combined into a single command that runs in a single shell.
|
|
20
|
+
|
|
21
|
+
## Show all changed files in the working tree
|
|
22
|
+
|
|
23
|
+
Shows all changed files (staged, unstaged, and untracked). Excludes deleted files and ignored files.
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
(git diff --cached --diff-filter=AM --name-only && git diff --diff-filter=AM --name-only && git ls-files --exclude-standard --others) | sort | uniq
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
## Show all changes in the branch
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
git diff $(git merge-base origin/main HEAD) HEAD
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Show commit count by author
|
|
36
|
+
|
|
37
|
+
```bash
|
|
38
|
+
git shortlog -s -n origin/main..HEAD
|
|
39
|
+
```
|