@drawbridge/drawbridge-agents 0.1.55 → 0.1.58

package/.claude-template/skills/drawbridge-asana-comment/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: drawbridge-asana-comment
+description: Use before posting ANY comment to an Asana task — ship handoffs, answers, status notes, questions. Enforces scannable lists of actions over paragraphs, plain correctly-named things, a mandatory review before posting, and the humanizer pass.
+---
+
+# Write an Asana comment
+
+Every comment posted to Asana goes through this skill. No exceptions for length, urgency, or
+"it's just a quick note". Posting is publishing. A teammate reads it, acts on it, and cannot
+unread a wrong one.
+
+Four rules, in order of how often they get broken.
+
+## 1. Lists and actions, not paragraphs
+
+There is no word count. Length is not the problem, shape is. Structure it so the reader can
+scan it and act.
+
+**The default shape:**
+
+- One line on what changed, in plain past tense.
+- A list of what to do and what to expect. One step per line, each one something they can
+  actually do or check.
+- Anything that would otherwise look wrong to them, as its own line.
+
+Use prose only for something a list would distort, like a one-sentence cause. Never write three
+paragraphs where four bullets would do.
+
+**Every line earns its place.** Cut it if it is:
+
+- The investigation narrative. They want the outcome, not how you got there.
+- File names, commit SHAs, function names, branch names. They are verifying behaviour.
+- Anything restating what they already told you.
+- Anything that would not change what they do next.
+
+**Completeness beats brevity.** Include every scenario to retest, any setup gotcha, and
+anything in the result that would look wrong without warning. A second comment correcting or
+completing the first is the real failure. Structure is what keeps a complete comment readable,
+so restructure before you cut content.
+
+**The stop test:** if it does not fit on a phone screen without scrolling, restructure it. Do
+not trim facts to hit a length.
+
+## 2. Use normal words and name things correctly
+
+Write for the person reading it, not for the repo.
+
+- **No internal jargon.** If the term lives in our docs and not in their message, replace it
+  with a plain description. Runbook, backfill, cascade, manifest, provider row, seam, capped,
+  hydrate all read as noise to someone testing a button. If you must use one, say what it is
+  the first time.
+- **Name things by their real name.** The screen, the button, the plan, the setting, exactly as
+  the interface labels them. Not your paraphrase, not the variable name. If the button says
+  Send, write Send.
+- **Quote user-facing copy exactly**, so they can match it against what is on screen.
+- Use their words for their bug. If they called it a prize notification, it is a prize
+  notification, not a lead-facing transactional send.
+
+## 3. Review before posting, always
+
+Never post a first draft. Read it back against this list:
+
+- Is it a scannable list of actions, or did it drift back into paragraphs?
+- **Is every claim verified?** Each factual statement must be something you checked in this
+  session: a test you ran, a deploy you confirmed live, a value you read. Anything you merely
+  believe gets cut or marked unverified. A wrong comment is worse than a thin one and costs
+  them a retest.
+- Any jargon they have not used themselves?
+- Does it open with `<a data-asana-gid="<their gid>"/>` so they are actually notified?
+- Would this need a follow-up comment? Fix that now.
+
+Then show the user the final text and get a go-ahead before posting, unless they have already
+said to proceed. After posting, read the comment back (`get_task` with comments) and confirm
+the mention expanded and the formatting survived. Asana silently flattens some markup.
+
+## 4. Run it through `humanizer`
+
+Required by `conventions/humanized-copy.md`, no exceptions for length. It must not touch the
+mention markup, quoted interface copy, or any concrete step. If a pass makes an instruction
+vaguer, keep the original for that line. If humanizer is unavailable, say so and do not post.
+
+## Sound like a teammate
+
+The comment should read as though the person who did the work wrote it in a hurry, because that
+is what a good one is.
+
+- **Plain past tense about what you did.** "Fixed on dev." Not "the fix has been implemented"
+  or "this has now been addressed".
+- **No throat-clearing.** No "Thanks for flagging this", "Great catch", "Just wanted to let you
+  know", "I hope this helps", "Let me know if you have questions".
+- **No hedging stack.** Not "this should now potentially resolve". Either it works and you saw
+  it work, or you say what you did not check.
+- **Own a mistake in one line and move on.** "I had this wrong, it only affects email." Not a
+  paragraph of explanation.
+- **Say what you did not test.** Being straight about a gap is what makes the rest credible.
+- **Ask a real question when you need an answer**, at the end, as a question. Do not bury it.
+- **Bold almost nothing.** If everything is bold, nothing is.
+- **No emoji** unless the thread already uses them.
+
+## Notes
+
+- Plain prose goes in `text`. Use `html_text` for a mention or a list. Allowed tags are
+  `<body> <strong> <em> <code> <ol> <ul> <li> <a> <blockquote> <pre>` only.
+- The `<a data-asana-gid="..."/>` form expands to a real @-mention. Reassignment alone is easy
+  to miss, so mention the person even when you also reassign.
+- If the Asana MCP is not connected, stop and say so. Never describe a comment as posted when
+  it was not.

package/.claude-template/skills/drawbridge-asana-ship-handoff/SKILL.md

@@ -1,69 +1,44 @@
 ---
 name: drawbridge-asana-ship-handoff
-description: Use when a feature has shipped (merged to develop) against an Asana task — reassigns the task back to its last commenter, posts a concise summary of what changed plus retest/verify steps, and sets the due date to now.
+description: Use when a feature has shipped (merged to develop) against an Asana task — reassigns the task back to its last commenter, posts a concise retest summary, and sets the due date to today.
 ---
 
 # Asana ship handoff
 
 Hand a shipped feature back to whoever last commented on its Asana task, with everything they
-need to retest. Use this right after merging the work to `develop` (which deploys to dev).
+need to retest. Use this right after merging to `develop` (which deploys to dev).
 
 ## Inputs
 
-- The Asana task URL or ID for the shipped work. Ask the user for it if it isn't obvious from
-  the branch, PR, or conversation — do not guess.
-- The change you shipped (from the diff / PR).
+- The Asana task URL or ID. Ask for it if it isn't obvious from the branch, PR, or
+  conversation. Do not guess.
+- The change you shipped.
 
 ## Steps
 
-1. **Load the task.** `asana_get_task` with the task gid (extract it from the URL).
-2. **Find the last commenter.** `asana_get_stories_for_task`, filter to comment stories
-   (`type` / `resource_subtype` is a comment, not a system story), take the **most recent**
-   one's `created_by`. This is the reassignee — do not hardcode a person. If there are no
-   comments, ask the user who to assign to.
-3. **Draft the comment — short.** Two parts, nothing else: what changed (and, if they
-   reported a bug, what actually caused it), then a **Retest** section with the steps and
-   the expected result. Ground the steps in the behaviour that actually changed.
-
-   **Hard limit: ~200 words, and never more than 6 short paragraphs/bullets.** These
-   comments have been far too long — reading them costs the reader more than the fix did.
-   Cut: the investigation narrative, why the bug shipped, code/file/commit detail, anything
-   restating what they already reported, and any sentence that would not change what they
-   do next.
-
-   **Short is not partial.** Include everything they need in ONE comment — every scenario to
-   retest, any setup or data gotcha, and anything about the result that would otherwise look
-   wrong (an odd amount, a delay, a cosmetic leftover). A follow-up comment correcting or
-   completing this one is the failure this limit exists to prevent, so check the draft for
-   omissions *before* trimming words.
-
-   **Open with an @-mention of the reassignee** — use `html_text` and start the body with
-   `<a data-asana-gid="<their user gid>"/>` (Asana expands it into a proper mention). A
-   comment without a mention may notify no one; reassignment alone is easy to miss.
-4. **Run the draft through `humanizer`.** A real teammate reads this, and generated-sounding
-   prose reads as effort nobody spent. Invoke the `humanizer` skill on the drafted body: it
-   strips the AI tells — inflated claims, hedging, stock transitions, "it's worth noting",
-   restating the ask twice.
-
-   It pulls in the same direction as the word limit above, so apply it *before* the final
-   trim and re-check the result against both rules. Two things it must not touch: the
-   `<a data-asana-gid="..."/>` mention (leave the markup exactly as-is) and any concrete
-   detail from the Retest steps — if a pass makes the steps vaguer, keep the original wording.
-5. **Confirm before writing.** This posts to an external system. Show the user the chosen
-   assignee and the drafted comment and get a go-ahead, unless they've told you to proceed
-   without asking.
-6. **Apply** (on approval):
-   - `asana_update_task` — set `assignee` to the last commenter's gid and `due_at` to the
-     current date/time (ISO 8601).
-   - `asana_create_task_story` — post the comment.
-7. **Report** the task URL, who it was assigned to, and confirm the due date was updated.
+1. **Load the task.** `get_task` with the gid from the URL.
+2. **Find the reassignee.** `get_task_stories`, filter to stories whose `resource_subtype` is
+   `comment_added`, take the most recent one's `created_by`. Do not hardcode a person. If there
+   are no comments, the task's creator is the fallback, but say so and confirm it.
+3. **Write the comment with `drawbridge-asana-comment`.** That skill owns the shape, the naming
+   rules, the humanizer pass, claim verification and the read-back. Do not restate its rules
+   here or work around them.
+
+   What this comment specifically must carry: what changed, and if they reported a bug, what
+   actually caused it; then the steps to retest and the expected result. Ground the steps in
+   the behaviour that changed, not in the diff.
+4. **Apply**, once the user has approved the text:
+   - `update_tasks` with `assignee` set to their gid and `due_on` set to today (`YYYY-MM-DD`).
+     The MCP cannot set a due *time*, only a date, so do not try to pass `due_at`.
+   - `add_comment` with `html_text`.
+5. **Report** the task URL, who it went to, and the due date. Confirm from the tool result, not
+   from intent.
 
 ## Notes
 
-- If the Asana MCP isn't connected, stop and tell the user to authorize it — don't fabricate a
-  handoff.
-- Keep the comment user/QA-facing: what to test and expect, not internal implementation detail.
-  The reader is verifying behaviour, not reviewing the fix — if a sentence only makes sense to
-  someone who has read the diff, it does not belong in the comment.
-- Consider running `drawbridge-ship-feature` instead if docs/graph updates for this ship
-  haven't been done yet — this skill is the final step of that flow.
+- Keep it QA-facing: what to test and expect. If a sentence only makes sense to someone who has
+  read the diff, it does not belong in the comment.
+- Run `drawbridge-ship-feature` instead if the docs and graph updates for this ship have not
+  been done yet. This skill is the last step of that flow.
+- If the Asana MCP isn't connected, stop and say so. Never describe a handoff that did not
+  happen.

package/claude/CLAUDE.md

@@ -2,6 +2,7 @@
 @../conventions/cross-repo-contracts.md
 @../conventions/karpathy-guidelines.md
 @../conventions/rules.md
+@../conventions/verification.md
 @../conventions/javascript-formatting.md
 @../conventions/nested-objects.md
 @../conventions/jsx-fragments.md
@@ -19,3 +20,4 @@
 @../conventions/git-branching.md
 @../conventions/graphify.md
 @../conventions/testing.md
+@../conventions/workflow-step-naming.md

package/conventions/humanized-copy.md

@@ -18,6 +18,8 @@ descriptions — engineer-facing text follows the code conventions instead.
 Rules when running it:
 
 - Run humanizer BEFORE posting/committing the copy, not after someone flags it.
+- **Asana comments go through the `drawbridge-asana-comment` skill**, which runs the humanizer
+  pass for you along with the brevity cap and the read-back. Do not hand-roll a comment.
 - It must not change facts, numbers, steps, or expected results — if a pass makes concrete
   instructions vaguer, keep the original wording for those parts.
 - Leave markup intact (Asana mention tags, links, placeholders like `{name}`).

package/conventions/rules.md

@@ -12,3 +12,9 @@
    This is not a style preference, it is the difference between advice and noise. Asserting a limitation that isn't real sends the reader to check your work, and asserting two implementations are identical when one carries a field the other drops ships a regression. Both have happened.
 
    In practice: before claiming a component can't do something, read the component. Before calling two implementations equivalent, read both ends to end. Before proposing a new endpoint or field to work around a gap, confirm the gap exists in the code rather than in your sample of it.
+
+6. Prove absence before you claim it, and name the space you searched. "Nothing writes this field", "that isn't documented anywhere", "no caller does this" — claims of that shape cost far more to establish than they look. Reading one file proves what that file does; it can never prove what every other file doesn't. Search the whole space the claim covers — every repo, the built `dist/` as well as the source, `drawbridge-docs/user-stories/` as well as the code, and the tests — then put the space in the sentence: "no writer across the family, source and dist" rather than "nothing writes it".
+
+   Why: the reader cannot see where you stopped looking. A bare "it doesn't exist" reads as settled, and by the time the thing turns up — documented under an older name, written by a manifest in another package — work has already been built on top of it. Naming the search space turns an unfalsifiable claim into one that can be checked in seconds.
+
+   Three traps that have actually caused this. A counter incremented from a manifest in `drawbridge-utils` while the search only covered `drawbridge-sync`. A workflow step documented under a name the product had since changed, so searching for the product's label found nothing. A key assembled at runtime (`'totals.' + field`) that no search for the literal will ever match — when a claim depends on a name, check whether the name is ever built rather than written.

package/conventions/verification.md

@@ -0,0 +1,39 @@
+# Verify before you assert
+
+Every rule here was written after a confident, wrong statement reached Darren. They share one shape: the reasoning was sound and the input was never checked. Sound reasoning on an unchecked input is the most expensive kind of wrong, because nothing downstream looks suspicious.
+
+## Never state a number you did not measure
+
+A measurement in a sentence — a count, a total, "none in the last 30 days" — may only be emitted when the underlying field is actually present. Gate on `value != null` before the claim and say nothing when it is absent.
+
+`|| 0` on an unmeasured field manufactures a fact. In drawbridge-growth it reached three surfaces at once: the task queue, profile embeddings, and outreach drafts telling paying customers they had done nothing, all from a field no connected database was filling.
+
+The same applies to prose. "This is faster", "most callers do X", "that's a small table" are measurements. Measure them or drop them.
+
+## Walk the flow before saying it works
+
+Tests passing, lint clean and a green build are not evidence that a screen works. Three bugs in a row survived all three and were found by clicking: a `.then()` chained off a react-query `mutate()` (which returns undefined), colour swatches handed `{ hex, name }` objects where CSS wanted a string, and a screen in a question flow that asked nothing.
+
+Before reporting a feature as working, run the path a person takes through it. If the runtime makes that hard, that is a reason to fix the harness, not to skip the walk.
+
+## Fetch before claiming what is on a branch
+
+Before asserting what is or isn't on `origin/develop` or `origin/main`, run `git fetch` **in that repo**. Fetching one family repo does not refresh the others, and grepping a stale `origin/develop` returns stale content with no warning.
+
+In a multi-repo check, fetch every repo you will cite, in one batch, first. Treat an `origin/<branch>` read as evidence only if the fetch happened in this session. "Repo A ships a write that repo B's schema rejects" is exactly the shape a stale ref produces — re-fetch, or read the live database, before reporting it.
+
+## Quote vendor documentation, do not recall it
+
+When writing against a vendor's API, open its documentation and quote each literal as you write it: authorize url, token url, revoke url, API base, required headers, scope names, auth scheme. Then re-read the finished file against the docs as a separate pass, paying most attention to the lines written first.
+
+Klaviyo's `authorize` host was written from memory as `a.klaviyo.com` — the API host — while the browser-facing url is `www.klaviyo.com`. The docs were fetched five times that session for the values that felt uncertain, and never for the one already written. Confidence is not verification, and the values never doubted are the ones that reach a user unchecked.
+
+Pin the API **version** too. Documentation defaults to `latest`; a repo pins something older, and a field that exists in `latest` may not exist in the pinned version — or may be deprecated there when it is current in `latest`.
+
+## Check the shape you are consuming, not the one you expect
+
+Before importing, confirm the symbol is actually exported by that package's entry point. Before chaining off a wrapper's return value, confirm what it returns. Both have shipped inert code that compiled cleanly.
+
+## A build that exits 0 is not a build that ran
+
+Confirm the build produced its real output — a route table, an emitted bundle, a written artifact — rather than trusting the exit code. `drawbridge-app-web` aborts on a missing environment variable and still exits 0, which is a "successful" build that compiled nothing.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drawbridge/drawbridge-agents",
-  "version": "0.1.55",
+  "version": "0.1.58",
   "description": "Shared agent-instruction content (rules, code style, conventions) for the drawbridge-* monorepo.",
   "license": "UNLICENSED",
   "publishConfig": {