refactor(fathom)!: rename plugin and skills from workbench to fathom - #8
Conversation
Renames the plugin, the shared-contract skill directory, the consumer-repo state directory, the merge-closer workflow, and the full guide. - Plugin name: workbench -> fathom (plugin.json, marketplace.json, README). - Shared skill directory: skills/workbench-shared -> skills/fathom-shared, with every ../workbench-shared/*.md reference in execute and scaffold updated to match. - Consumer state directory: .workbench/ -> .fathom/, covering config.md, tasks/<ref>.md, plans/<ref>.md, and forge.md across the skills and guide. - Merge-closer Action: .github/workflows/workbench-close.yml -> fathom-close.yml, and the workflow name inside the Asana and Linear templates. - Guide: docs/workbench.md -> docs/fathom.md. Version bumped to 2.0.0 through bin/sync-versions.sh, since the install name and the state directory both move. Two rename-safety changes go with it: The done-on-merge sweep now also reads the legacy "workbench: review-closed-unmerged" sentinel when matching, and still only ever writes the current one. That sentinel is a comment on the tracker issue rather than a file in the repository, so no rename reaches the ones already sitting in Asana and Linear. Without the read-side fallback, every abandoned review a user had already triaged would be re-reported on the first 2.0.0 sweep, as a stop that fires even in auto mode. docs/fathom.md gains a "From workbench 1.x to Fathom 2.0.0" section. It covers the base branch and, in step 6, every unmerged feature branch: execute commits each issue's plan and checklist on its own branch, so a base-only rename strands them. The step-6 command order is load-bearing and was verified by running it against synthetic 1.x repositories with both checklist-backed and beads-backed branches. Product name is capitalized in prose because "fathom" is also a common verb. Identifiers stay lowercase: fathom:execute, fathom@crod951, and the literal "# fathom tracker profile" header, which bin/sync-versions.sh also matches against. Historical records under docs/plans/, .superpowers/, and .beads/ keep the old name deliberately. BREAKING CHANGE: the plugin installs as fathom@crod951 rather than workbench@crod951, and task state moves from .workbench/ to .fathom/. There is no automatic migration. Existing repositories must follow the "From workbench 1.x to Fathom 2.0.0" section of docs/fathom.md, including step 6 for branches that are still in flight; a base-only rename leaves those branches invisible to 2.0.0.
ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (21)
📝 WalkthroughWalkthroughThe plugin is renamed from Workbench to Fathom and updated to version 2.0.0. Documentation, shared skill paths, repository state directories, forge adapters, tracker workflows, and execution instructions now use Fathom terminology. Generic Git, GitHub, and beads contracts were added. ChangesFathom identity and documentation
Estimated code review effort: 3 (Moderate) | ~20 minutes Possibly related PRs
Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@skills/execute/SKILL.md`:
- Line 116: Update the completion flow around the final closing commit to define
how adapters with pushesForYou: true publish that commit, adding a contract
operation that pushes the correct branch/ref before returning, or explicitly
reject those adapters from reaching this flow. Ensure the final task-state
commit is neither pushed to an unintended ref nor left only in the local
workspace.
In `@skills/fathom-shared/forges/generic-git.md`:
- Around line 54-57: Update the no-review-id handling in the generic Git forge
flow to state explicitly that no forge review was opened, the tracker phase is
inReview, and the user must manually close the handoff. Ensure the run’s
reporting does not describe the work as “in review” when no review exists.
- Around line 28-33: Update verifyForge() to validate remote reachability with
git ls-remote origin >/dev/null, without requiring the remote to advertise HEAD.
Leave the branch-specific HEAD check in resolveBase() unchanged.
In `@skills/fathom-shared/memory/beads.md`:
- Around line 13-15: Update the createTask and close workflows to make beads
writes durable and resumable: execute the subIssueRef update with bd
--no-daemon, persist the created task ID and each completed write step so
retries resume without duplicating tasks or links, and record the implementation
commit’s short hash with bd update <taskId> --notes before running bd close.
In `@skills/fathom-shared/trackers.md`:
- Line 217: Update forge adapter resolution to handle forge: local explicitly:
require .fathom/forge.md and report clear repair instructions when it is absent,
rather than falling through to forges/local.md. Keep the existing
bundled-adapter resolution for other forge values, or remove local from the
documented profile vocabulary if local support is not intended.
In `@skills/fathom-shared/trackers/asana.md`:
- Around line 127-128: Replace the broad grep-based matching in the merge-closer
templates with parsing that extracts the labeled branch field and selects only
files whose field exactly equals BRANCH. Apply this change at
skills/fathom-shared/trackers/asana.md lines 127-128 and
skills/fathom-shared/trackers/linear.md lines 115-116, preserving the existing
match-count and selection behavior after exact filtering.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: dbf9b5b9-acd5-41e6-a901-b35f60c7424e
📒 Files selected for processing (21)
.claude-plugin/marketplace.json.claude-plugin/plugin.json.skillspector-baseline.yamlREADME.mddocs/fathom.mdskills/execute/SKILL.mdskills/fathom-shared/SKILL.mdskills/fathom-shared/agents.mdskills/fathom-shared/approval.mdskills/fathom-shared/conventions.mdskills/fathom-shared/forges.mdskills/fathom-shared/forges/TEMPLATE.mdskills/fathom-shared/forges/generic-git.mdskills/fathom-shared/forges/github.mdskills/fathom-shared/memory.mdskills/fathom-shared/memory/beads.mdskills/fathom-shared/memory/checklist.mdskills/fathom-shared/trackers.mdskills/fathom-shared/trackers/asana.mdskills/fathom-shared/trackers/linear.mdskills/scaffold/SKILL.md
| Still apply `inReview`, and say plainly that no later run will move this issue to `done` on its own because the forge cannot be observed, so closing it is now a manual step. | ||
|
|
||
| Finally, post a completion comment on the issue, including the done-on-merge note from `asana.md` when the tracker is Asana, and commit and push the task-state files this run changed as a final closing commit so the branch carries the completed state, staging them by explicit path per the staging rules in `conventions.md`: the beads JSONL export and `metadata.json` when beads is the backend, and this issue's files under `.workbench/`; never sweep `.beads/` or `.workbench/` as directories, since the beads database and runtime files are intentionally ignored and must not ride into the review. | ||
| Finally, post a completion comment on the issue, including the done-on-merge note from `asana.md` when the tracker is Asana, and commit and push the task-state files this run changed as a final closing commit so the branch carries the completed state, staging them by explicit path per the staging rules in `conventions.md`: the beads JSONL export and `metadata.json` when beads is the backend, and this issue's files under `.fathom/`; never sweep `.beads/` or `.fathom/` as directories, since the beads database and runtime files are intentionally ignored and must not ride into the review. |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
🧩 Analysis chain
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
rg -n -C 5 'pushesForYou|openReview|publishReview|final closing commit|commit and push' \
skills/fathom-shared skills/executeRepository: crod951/skills
Length of output: 29058
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
printf '%s\n' '--- execute flow ---'
sed -n '84,121p' skills/execute/SKILL.md
printf '%s\n' '--- forge contract ---'
sed -n '1,95p' skills/fathom-shared/forges.md
printf '%s\n' '--- adapter capability declarations ---'
rg -n -C 6 'pushesForYou|## `openReview|Push the branch|push the branch|final closing commit' \
skills/fathom-shared/forges .fathom 2>/dev/null || true
printf '%s\n' '--- all repository references ---'
rg -n -C 3 'pushesForYou|final closing commit|commit and push|git push|push the branch' \
--glob '!node_modules/**' --glob '!dist/**' --glob '!build/**' .Repository: crod951/skills
Length of output: 50372
Define the post-review push behavior for pushesForYou adapters.
The contract only assigns push ownership to openReview, but the final closing commit occurs afterward. Add a contract operation for publishing that commit, or prevent pushesForYou: true adapters from reaching this flow. A direct git push can target the wrong ref, while omitting the push leaves the final task state local.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@skills/execute/SKILL.md` at line 116, Update the completion flow around the
final closing commit to define how adapters with pushesForYou: true publish that
commit, adding a contract operation that pushes the correct branch/ref before
returning, or explicitly reject those adapters from reaching this flow. Ensure
the final task-state commit is neither pushed to an unintended ref nor left only
in the local workspace.
There was a problem hiding this comment.
Valid observation, but pre-existing and out of scope for this PR.
This line is byte-identical to origin/main apart from the mechanical .workbench/ -> .fathom/ path swap, so the rename neither introduces nor worsens the gap. Defining a contract operation for publishing the final closing commit changes the shipped forge contract and would need its own testing against both bundled adapters, which does not belong in a mechanical rename.
Tracking as a follow-up rather than folding it in here. Disposition: acknowledged, deferred.
There was a problem hiding this comment.
@crod951, acknowledged. The rename does not introduce or worsen this contract gap.
A change to publish the final task-state commit for pushesForYou adapters requires a separate forge-contract change and adapter validation. Deferring it is appropriate for this PR.
Would you like me to create a GitHub follow-up issue for this work?
You are interacting with an AI system.
| # fathom tracker profile | ||
| tracker: asana | ||
| forge: github # a bundled adapter name, "local" for .workbench/forge.md, or "none" | ||
| forge: github # a bundled adapter name, "local" for .fathom/forge.md, or "none" |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Handle forge: local explicitly during adapter resolution.
The profile format permits forge: local, but skills/fathom-shared/forges.md only defines the repo-local path when .fathom/forge.md exists. Otherwise it resolves a bundled adapter named by forge. A missing local adapter can therefore fall through to a nonexistent forges/local.md.
Require .fathom/forge.md when the profile says local and report repair instructions, or remove local from the profile vocabulary.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@skills/fathom-shared/trackers.md` at line 217, Update forge adapter
resolution to handle forge: local explicitly: require .fathom/forge.md and
report clear repair instructions when it is absent, rather than falling through
to forges/local.md. Keep the existing bundled-adapter resolution for other forge
values, or remove local from the documented profile vocabulary if local support
is not intended.
There was a problem hiding this comment.
Valid observation, but pre-existing and out of scope for this PR.
origin/main carries the same line with .workbench/forge.md in place of .fathom/forge.md; only the path inside the trailing comment changed. The forge: local resolution gap is real and predates the rename.
Tightening adapter resolution means editing the forge contract in forges.md, which is exactly the kind of behavioural change a rename PR should not carry. Tracking as a follow-up. Disposition: acknowledged, deferred.
There was a problem hiding this comment.
@crod951, acknowledged. The forge: local resolution gap is pre-existing and does not result from this rename.
I will leave this finding deferred for the follow-up work. Would you like me to create a GitHub issue for it?
You are interacting with an AI system.
| MATCHES=$(grep -rlF "$BRANCH" .fathom/ 2>/dev/null | sort) | ||
| MATCH_COUNT=$(printf '%s' "$MATCHES" | grep -c . || true) |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick win
Use exact branch-field matching in both merge-closer templates.
Both workflows search all .fathom/ content with grep -rlF "$BRANCH". Substring or prose matches can select a stale record, close the wrong tracker item, or cause a false multi-match refusal.
skills/fathom-shared/trackers/asana.md#L127-L128: parse and exact-match the labeled branch field before selecting the Asana task file.skills/fathom-shared/trackers/linear.md#L115-L116: parse and exact-match the labeled branch field before selecting the Linear issue file.
📍 Affects 2 files
skills/fathom-shared/trackers/asana.md#L127-L128(this comment)skills/fathom-shared/trackers/linear.md#L115-L116
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@skills/fathom-shared/trackers/asana.md` around lines 127 - 128, Replace the
broad grep-based matching in the merge-closer templates with parsing that
extracts the labeled branch field and selects only files whose field exactly
equals BRANCH. Apply this change at skills/fathom-shared/trackers/asana.md lines
127-128 and skills/fathom-shared/trackers/linear.md lines 115-116, preserving
the existing match-count and selection behavior after exact filtering.
There was a problem hiding this comment.
Valid observation, and the most interesting of the batch, but pre-existing and out of scope for this PR.
Both templates carry grep -rlF "$BRANCH" .fathom/ verbatim from origin/main, where they read .workbench/. The rename changed the searched directory and nothing about the matching semantics.
Moving to exact labelled-field matching rewrites the embedded merge-closer YAML that ships into consumer repositories, and per docs/fathom.md Known limitations the Linear template has never been run end to end. That needs its own PR with real verification, not a drive-by edit inside a rename. Tracking as a follow-up. Disposition: acknowledged, deferred.
There was a problem hiding this comment.
@crod951, acknowledged. The exact branch-field matching issue predates this PR and is not caused by the Fathom rename.
A separate change with end-to-end workflow verification is appropriate. Would you like me to create a GitHub follow-up issue for the Asana and Linear templates?
✏️ Learnings added
Learnt from: crod951
Repo: crod951/skills PR: 8
File: skills/fathom-shared/trackers/asana.md:127-128
Timestamp: 2026-08-07T20:16:43.369Z
Learning: In `skills/fathom-shared/trackers/asana.md` and `skills/fathom-shared/trackers/linear.md`, the merge-closer templates use broad `grep -rlF "$BRANCH"` discovery inherited from the pre-rename Workbench templates. Replacing it with exact labeled branch-field matching is deferred to a separate change because it modifies shipped consumer GitHub Actions workflows and requires end-to-end verification, especially for the Linear template.
Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.
You are interacting with an AI system.
There was a problem hiding this comment.
Caution
Inline review comments failed to post. This is likely due to GitHub's internal server error or limits when posting large numbers of comments. If you are seeing this consistently it is likely a permissions issue. Please check "Moderation" -> "Code review limits" under your organization settings.
Actionable comments posted: 6
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@skills/execute/SKILL.md`:
- Line 116: Update the completion flow around the final closing commit to define
how adapters with pushesForYou: true publish that commit, adding a contract
operation that pushes the correct branch/ref before returning, or explicitly
reject those adapters from reaching this flow. Ensure the final task-state
commit is neither pushed to an unintended ref nor left only in the local
workspace.
In `@skills/fathom-shared/forges/generic-git.md`:
- Around line 54-57: Update the no-review-id handling in the generic Git forge
flow to state explicitly that no forge review was opened, the tracker phase is
inReview, and the user must manually close the handoff. Ensure the run’s
reporting does not describe the work as “in review” when no review exists.
- Around line 28-33: Update verifyForge() to validate remote reachability with
git ls-remote origin >/dev/null, without requiring the remote to advertise HEAD.
Leave the branch-specific HEAD check in resolveBase() unchanged.
In `@skills/fathom-shared/memory/beads.md`:
- Around line 13-15: Update the createTask and close workflows to make beads
writes durable and resumable: execute the subIssueRef update with bd
--no-daemon, persist the created task ID and each completed write step so
retries resume without duplicating tasks or links, and record the implementation
commit’s short hash with bd update <taskId> --notes before running bd close.
In `@skills/fathom-shared/trackers.md`:
- Line 217: Update forge adapter resolution to handle forge: local explicitly:
require .fathom/forge.md and report clear repair instructions when it is absent,
rather than falling through to forges/local.md. Keep the existing
bundled-adapter resolution for other forge values, or remove local from the
documented profile vocabulary if local support is not intended.
In `@skills/fathom-shared/trackers/asana.md`:
- Around line 127-128: Replace the broad grep-based matching in the merge-closer
templates with parsing that extracts the labeled branch field and selects only
files whose field exactly equals BRANCH. Apply this change at
skills/fathom-shared/trackers/asana.md lines 127-128 and
skills/fathom-shared/trackers/linear.md lines 115-116, preserving the existing
match-count and selection behavior after exact filtering.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: dbf9b5b9-acd5-41e6-a901-b35f60c7424e
📒 Files selected for processing (21)
.claude-plugin/marketplace.json.claude-plugin/plugin.json.skillspector-baseline.yamlREADME.mddocs/fathom.mdskills/execute/SKILL.mdskills/fathom-shared/SKILL.mdskills/fathom-shared/agents.mdskills/fathom-shared/approval.mdskills/fathom-shared/conventions.mdskills/fathom-shared/forges.mdskills/fathom-shared/forges/TEMPLATE.mdskills/fathom-shared/forges/generic-git.mdskills/fathom-shared/forges/github.mdskills/fathom-shared/memory.mdskills/fathom-shared/memory/beads.mdskills/fathom-shared/memory/checklist.mdskills/fathom-shared/trackers.mdskills/fathom-shared/trackers/asana.mdskills/fathom-shared/trackers/linear.mdskills/scaffold/SKILL.md
🛑 Comments failed to post (3)
skills/fathom-shared/forges/generic-git.md (2)
28-33: 🩺 Stability & Availability | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/sh set -eu git ls-remote --exit-code "$REMOTE_URL" HEAD git ls-remote "$REMOTE_URL" >/dev/nullRepository: crod951/skills
Length of output: 195
🏁 Script executed:
#!/bin/sh set -eu printf '%s\n' '--- generic-git.md ---' cat -n skills/fathom-shared/forges/generic-git.md printf '%s\n' '--- related contract references ---' rg -n -C 4 'verifyForge|resolveBase|Tier 3|manual|handoff|tracker state|origin HEAD|ls-remote' \ skills/fathom-shared/forges skills/fathom-shared 2>/dev/nullRepository: crod951/skills
Length of output: 48984
🌐 Web query:
git ls-remote --exit-code HEAD behavior remote does not advertise HEAD official documentation💡 Result:
According to the official Git documentation, the --exit-code option for git ls-remote is designed to make the command exit with a status code of "2" when no matching references are found in the remote repository [1][2][3]. Normally, git ls-remote exits with a status of "0" if it successfully contacts the remote, regardless of whether any matching references are found [1][4]. When you execute git ls-remote --exit-code HEAD, Git treats HEAD as the pattern to match against the remote's advertised references [1]. If the remote does not explicitly advertise HEAD (or if the pattern fails to match any advertised reference), the command will fail to find a match and will consequently exit with status "2" [1][4][5]. This behavior allows scripts to programmatically detect the absence of a specific reference or the inability to resolve it on the remote side [6][7][8]. In practice, if a remote repository does not advertise HEAD—which is rare for standard Git servers but technically possible in certain custom or restricted environments—the --exit-code flag ensures the operation signals a "not found" condition rather than returning a silent success (exit 0) [4][8]. Therefore, if you require the presence of HEAD for your logic, checking for this specific exit code is the standard approach to handle its absence [6][8].
Citations:
- 1: https://git-scm.com/docs/git-ls-remote.html
- 2: https://git-scm.com/docs/git-ls-remote/2.46.0
- 3: https://git-scm.com/docs/git-ls-remote
- 4: https://public-inbox.org/git/20110512120536.GA22033@camk.edu.pl/T/
- 5: https://github.com/git/git/blob/maint/builtin/ls-remote.c
- 6: https://stackoverflow.com/questions/30787252/git-push-to-remote-but-dont-create-new-branch
- 7: https://stackoverflow.com/questions/75400773/is-git-ls-remote-able-to-use-github-variables-error-process-completed-with-exi
- 8: https://latchkey.dev/learn/command-reference/git-ls-remote-heads
🏁 Script executed:
#!/bin/sh set -u remote_url=$(git remote get-url origin 2>/dev/null || true) if [ -z "$remote_url" ]; then echo "origin is not configured" exit 0 fi echo "remote=$remote_url" set +e git ls-remote --exit-code "$remote_url" HEAD >/dev/null head_status=$? git ls-remote "$remote_url" >/dev/null reachability_status=$? set -e printf 'ls-remote --exit-code ... HEAD: %s\n' "$head_status" printf 'ls-remote without ref filter: %s\n' "$reachability_status" # A known absent ref distinguishes reachability from --exit-code's # "no matching reference" result without changing repository state. set +e git ls-remote --exit-code "$remote_url" \ 'refs/heads/__coderabbit_probe_ref_that_should_not_exist__' >/dev/null missing_ref_status=$? set -e printf 'ls-remote --exit-code ... missing ref: %s\n' "$missing_ref_status"Repository: crod951/skills
Length of output: 304
Use remote reachability without requiring
HEAD.
git ls-remote --exit-code origin HEADfails when a reachable remote does not advertiseHEAD. Usegit ls-remote origin >/dev/nullinverifyForge(), and keep the branch-specific check inresolveBase().🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skills/fathom-shared/forges/generic-git.md` around lines 28 - 33, Update verifyForge() to validate remote reachability with git ls-remote origin >/dev/null, without requiring the remote to advertise HEAD. Leave the branch-specific HEAD check in resolveBase() unchanged.
54-57: 🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/sh set -eu rg -n -C 5 'manual-handoff|inReview|openReview|in review' \ skills/execute/SKILL.md \ skills/fathom-shared/forges.md \ skills/fathom-shared/trackers.mdRepository: crod951/skills
Length of output: 16806
🏁 Script executed:
#!/bin/sh set -eu printf '%s\n' '--- generic-git.md ---' cat -n skills/fathom-shared/forges/generic-git.md printf '%s\n' '--- execute manual-handoff section ---' sed -n '96,120p' skills/execute/SKILL.md printf '%s\n' '--- shared manual-tier section ---' sed -n '136,148p' skills/fathom-shared/forges.mdRepository: crod951/skills
Length of output: 8142
Clarify the manual-handoff state and report.
skills/execute/SKILL.mdalready appliesinReviewand records no review ID. State explicitly that no forge review was opened, the tracker phase isinReview, and closure is manual.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skills/fathom-shared/forges/generic-git.md` around lines 54 - 57, Update the no-review-id handling in the generic Git forge flow to state explicitly that no forge review was opened, the tracker phase is inReview, and the user must manually close the handoff. Ensure the run’s reporting does not describe the work as “in review” when no review exists.skills/fathom-shared/memory/beads.md (1)
13-15: 🗄️ Data Integrity & Integration | 🟠 Major | 🏗️ Heavy lift
🧩 Analysis chain
🏁 Script executed:
#!/bin/sh set -eu bd version bd create --help bd update --help bd dep add --helpRepository: crod951/skills
Length of output: 192
🏁 Script executed:
#!/bin/sh set -eu printf '%s\n' '--- tracked files ---' git ls-files 'skills/fathom-shared/memory/beads.md' 'skills/fathom-shared/conventions.md' '*beads*' '*conventions*' printf '%s\n' '--- beads.md ---' cat -n skills/fathom-shared/memory/beads.md printf '%s\n' '--- relevant CLI references ---' rg -n -i --glob '!skills/fathom-shared/memory/beads.md' \ 'bd (create|update|close|dep add|ready|count)|beads|--external-ref|--notes|--claim|blocked' .Repository: crod951/skills
Length of output: 42078
🌐 Web query:
Beads CLI bd v0.49.0 documentation create update close dep add ready count --notes --external-ref --claim💡 Result:
The Beads CLI (bd) v0.49.0 is a tool for managing issues, workflows, and dependencies [1][2]. Below is a summary of the requested commands and flags based on the official documentation [3][4][5]. Core Commands: - bd create: Creates new issues with rich metadata [3][2]. - bd update: Updates issue fields or status [2][5]. - bd close: Closes issues with a specified reason [2]. - bd dep: Manages dependencies between issues [2]. - bd ready: Lists open, unblocked work [2][4]. - bd count: Displays counts of issues matching specific filters. Key Flags: - --notes string: Used with create or update commands to add additional notes to an issue [3][5]. - --external-ref string: Links a beads issue to an external reference, such as a GitHub issue (e.g., gh-9), Jira ticket, or URL [3][5][6]. - --claim: Used with the update command (e.g., bd update --claim) to atomically claim an issue, which sets the assignee to the current user and the status to in_progress [2][7][6]. General Usage: - Many commands support --json output for programmatic use [2][8]. - Documentation is available at https://beads.gascity.com/ [9]. - Installation can be performed via binary download, Homebrew, or shell scripts [1][10][9]. [1][10][3][9][2][4][5][7][6][8]
Citations:
- 1: https://github.com/gastownhall/beads/releases/tag/v0.49.0
- 2: https://mintlify.wiki/steveyegge/beads/cli/overview
- 3: https://gastownhall.github.io/beads/cli-reference/create
- 4: https://gastownhall.github.io/beads/cli-reference/ready
- 5: https://gastownhall.github.io/beads/cli-reference/update
- 6: https://github.com/toowiredd/beads/blob/main/claude-plugin/skills/beads/resources/CLI_REFERENCE.md
- 7: https://gastownhall.github.io/beads/next/cli-reference/update
- 8: https://github.com/dbmcco/tmux-beads-loops/blob/main/skills/beads/resources/CLI_REFERENCE.md
- 9: https://github.com/gastownhall/beads
- 10: https://gastownhall.github.io/beads/getting-started/installation
🌐 Web query:
site:gastownhall.github.io/beads v0.49.0 "bd create" "--deps" "--external-ref" "bd update" "--notes"💡 Result:
In the Beads (bd) CLI tool, the commands you provided are used for managing issue metadata and associations. bd create --deps --external-ref This command creates a new issue with specific configurations: --deps (or similar dependency-related flags): While --deps is not explicitly listed as a standalone flag in the standard 'bd create' documentation [1][2][3], dependency relationships are generally managed via the 'bd dep' command [4]. If you are creating a graph of issues, the --graph flag allows importing a JSON plan file containing dependencies [1][2]. --external-ref string: This flag allows you to attach an external reference to the new issue (e.g., 'gh-9', 'jira-ABC', or a Linear URL) [1][2][3]. bd update --notes This command modifies an existing issue: --notes string: This flag sets or updates the additional notes field for the target issue [5]. If no issue ID is provided, it defaults to the last touched issue [5]. Additional context: If you want to append notes to an issue rather than overwriting them, you can use the 'bd note' command, which is a shorthand for 'bd update --append-notes' [6]. To interactively edit the notes field using your system's text editor, you can use 'bd edit --notes' [7]. Note: The information provided is based on the Beads CLI documentation (v1.0.4/1.0.5) [1][5][4][6]. Ensure you are running a version compatible with these flags, as CLI features can evolve between versions [8].
Citations:
- 1: https://gastownhall.github.io/beads/cli-reference/create
- 2: https://gastownhall.github.io/beads/1.0.4/cli-reference/create
- 3: https://gastownhall.github.io/beads/next/cli-reference/create
- 4: https://gastownhall.github.io/beads/cli-reference/dep
- 5: https://gastownhall.github.io/beads/cli-reference/update
- 6: https://gastownhall.github.io/beads/cli-reference/note
- 7: https://gastownhall.github.io/beads/cli-reference/edit
- 8: https://gastownhall.github.io/beads/next/cli-reference/create-form
🏁 Script executed:
#!/bin/sh set -eu for url in \ 'https://raw.githubusercontent.com/gastownhall/beads/v0.49.0/cmd/bd/commands/create.go' \ 'https://raw.githubusercontent.com/gastownhall/beads/v0.49.0/cmd/bd/commands/update.go' \ 'https://raw.githubusercontent.com/gastownhall/beads/v0.49.0/cmd/bd/commands/close.go' do printf '\n--- %s ---\n' "$url" curl -fsSL "$url" | rg -n -C 3 -- '--deps|--external-ref|--notes|StringVar|BoolVar|closeReason|reason' doneRepository: crod951/skills
Length of output: 296
🏁 Script executed:
#!/bin/sh set -eu repo='gastownhall/beads' tag='v0.49.0' printf '%s\n' '--- tag resolution ---' curl -fsSL "https://api.github.com/repos/$repo/git/ref/tags/$tag" | jq '{object_type: .object.type, object_sha: .object.sha}' printf '%s\n' '--- candidate command files ---' curl -fsSL "https://api.github.com/repos/$repo/git/trees/$tag?recursive=1" | jq -r '.tree[].path' | rg '(^|/)(create|update|close|dep|ready|count)[^/]*\.(go|md)$|cmd/.+\.go$' | head -80Repository: crod951/skills
Length of output: 305
🌐 Web query:
Beads v0.49.0 CLI reference update --notes create --external-ref dependency flags💡 Result:
In the Beads CLI (v0.49.0), the --external-ref flag is used to associate an issue with an external system identifier (e.g., 'gh-9', 'jira-ABC', or a Linear URL) [1][2][3]. Key technical details and behavioral notes for this flag include: 1. CLI Usage: The flag is primarily used with the bd create command to link newly created issues to external references [1][2]. It is also intended to be used with the bd update command [4]. 2. Known Limitation (Daemon Mode): As of v0.49.0, there is a known issue where the --external-ref flag may be ignored when executing commands in the default daemon mode [4]. To ensure the external reference is correctly saved, it is recommended to use the --no-daemon flag [4]: bd --no-daemon create "Issue Title" --external-ref "your-ref" bd --no-daemon update --external-ref "new-ref" 3. Purpose: This flag supports workflows like Linear pre-linking, where issues are associated with existing external identifiers to prevent duplicates and maintain traceability [3]. For a complete reference, you can access the CLI documentation via the official Beads website or by running bd help in your terminal [5][6]. Please note that as of August 2026, the current version is significantly higher than 0.49.0, and documentation for current versions can be found at https://beads.gascity.com/ [6].
Citations:
- 1: https://gastownhall.github.io/beads/cli-reference/create
- 2: https://github.com/gastownhall/beads/blob/main/website/versioned_docs/version-1.0.5/cli-reference/create.md
- 3: gastownhall/beads#3517
- 4: gastownhall/beads#303
- 5: https://github.com/gastownhall/beads
- 6: https://gastownhall.github.io/beads/cli-reference
Make beads writes durable and resumable.
On
bd 0.49.0, daemon mode can ignore--external-ref; run the reference write withbd --no-daemon. Persist the task ID and completed steps because task creation, reference updates, and dependency additions are separate writes. This prevents duplicate tasks and missing links after a failed retry. Record the commit hash withbd update <taskId> --notes "<short-hash>"beforebd close <taskId>.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@skills/fathom-shared/memory/beads.md` around lines 13 - 15, Update the createTask and close workflows to make beads writes durable and resumable: execute the subIssueRef update with bd --no-daemon, persist the created task ID and each completed write step so retries resume without duplicating tasks or links, and record the implementation commit’s short hash with bd update <taskId> --notes before running bd close.
|
Disposition for the three findings CodeRabbit reported under "Comments failed to post (3)", quoted here since they never landed inline. 1. 2. 3. Disposition: all three acknowledged and deferred. Both files are byte-identical to Both produce no output. This PR moved them via All three are legitimate and worth doing, and each is a behavioural change to a shipped contract needing its own verification - the Same disposition as the three inline findings, which are also pre-existing and answered individually above. Six for six: valid, pre-existing, deferred to follow-up work. |
1 participant
Renames the plugin from
workbenchtofathom, end to end, with no migration shim. Version bumped1.1.0->2.0.0through the repo's ownbin/sync-versions.sh.What moved
workbenchfathomskills/workbench-shared/skills/fathom-shared/.workbench/.fathom/workbench-close.ymlfathom-close.ymldocs/workbench.mddocs/fathom.mdgit mvthroughout, so rename history is preserved.Two rename-safety changes
The legacy abandonment sentinel is still read.
workbench: review-closed-unmergedis written as a comment on the tracker issue, not a file in the repo, so no rename reaches the ones already sitting in Asana and Linear. The sweep now matches both sentinels and writes only the current one. Without this, every abandoned review a user had already triaged would be re-reported on the first 2.0.0 sweep, as a stop that fires even in auto mode.The migration covers in-flight branches.
executecommits each issue's plan and checklist on its own feature branch, so renaming only on the base strands them. Step 6 of the new upgrade section handles those branches, and its command order is load-bearing: renaming after merging the base turnsgit mv .workbench .fathomfrom a rename into a move-inside.Verification
Run against every gate CI uses, plus a few it doesn't:
bin/scan-skills.shPASS - execute 0 findings,fathom-shared8 suppressed, scaffold 2 suppressed. Run repeatedly, since SkillSpector's static filtering is non-deterministic.plugin.json/marketplace.jsonparse and agree onfathom@2.0.0; baseline YAML parses.bin/sync-versions.shis a no-op against the tree, so no generated field was hand-edited into drift.../fathom-shared/*.mdcross-references resolve; alldocs/fathom.mdanchors resolve.workbenchleft in shipped surface except the deliberate legacy references (migration steps, legacy sentinel, one limitation note)..fathom/tree,.beads/preserved, no strays. An earlier draft of that block passed review and then failed when actually run.Four review rounds; findings fixed and re-verified each round.
Breaking
Installs as
fathom@crod951, and state moves to.fathom/. No automatic migration - existing repos follow the new "From workbench 1.x to Fathom 2.0.0" section, including step 6 for branches still in flight.Known follow-ups, not in this PR
skills/. Left alone to keep a mechanical rename reviewable and avoid churning contract prose.SKILL.mdfiles still carryversion: 1.0.0.sync-versions.shdoes not touch those, so they track the skill rather than the plugin; flagging in case they were meant to move.Summary by CodeRabbit
New Features
Enhancements
.fathom.Documentation