Share agent workflows via installed skills + repo seam#4121
Conversation
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
WalkthroughReplaces a git-subtree sync script approach with a seam-based portability model for shared agent workflows. A new Ruby ChangesPortable Agent Workflows via Seam Model
Sequence DiagramsequenceDiagram
participant Adopter as Repo Adopter
participant Shared as Shared Skills (installed)
participant Seam as AGENTS.md Seam
participant Doctor as agent-workflow-seam-doctor
participant Workflow as Workflow Execution
Adopter->>Adopter: Install shared skills
Adopter->>Seam: Define Agent Workflow Configuration
Adopter->>Doctor: Run seam doctor validation
Doctor->>Seam: Extract & parse config
Doctor->>Doctor: Validate required keys
Doctor->>Doctor: Scan for unresolved placeholders
Doctor-->>Adopter: PASS / FAIL + issues
Adopter->>Workflow: Trigger workflow (e.g., pr-batch)
Workflow->>Shared: Load installed skill module
Shared->>Seam: Resolve config values
Seam-->>Shared: Return repo-specific commands/labels
Shared->>Workflow: Execute with seam-resolved values
Workflow-->>Adopter: Result
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related issues
Possibly related PRs
Suggested labels
Suggested reviewers
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
Bugbot Autofix is ON. A cloud agent has been kicked off to fix the reported issue.
Reviewed by Cursor Bugbot for commit dcf3135. Configure here.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: dcf3135615
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Greptile SummaryThis PR makes the 19 shared
Confidence Score: 4/5Safe to merge with one targeted fix in address-review/SKILL.md. The genericization is thorough and consistent across 18 files — every seam reference uses a prose indirection pattern except for one: the .agents/skills/address-review/SKILL.md — the angle-bracket placeholder in the Important Files Changed
Reviews (1): Last reviewed commit: "docs: rewrite agent-workflow adoption gu..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (3)
docs/superpowers/specs/2026-06-18-portable-agent-workflows-subtree-design.md (1)
112-112: 💤 Low valueCapitalize "Markdown" as a proper noun.
Lines 112 and 156 refer to "markdown format" and "markdown links"; the formatting language is "Markdown" (proper noun).
🔤 Proposed capitalization fixes
- validation gate (markdown format + link check + skill `bin/` test... + validation gate (Markdown format + link check + skill `bin/` test... - Dry-run gate (above). - `bin/check-links` (lychee) for markdown links. + Dry-run gate (above). - `bin/check-links` (lychee) for Markdown links.Also applies to: 156-156
🤖 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 `@docs/superpowers/specs/2026-06-18-portable-agent-workflows-subtree-design.md` at line 112, Capitalize "markdown" to "Markdown" in two locations within the document since Markdown is the proper noun name of the formatting language. On line 112, change "markdown format" to "Markdown format". On line 156, change "markdown links" to "Markdown links". Both instances need the first letter of the word capitalized to correctly reference the proper noun.internal/contributor-info/agent-workflow-adoption.md (2)
117-117: 💤 Low valueCapitalize "Markdown" as a proper noun.
Line 117 refers to "markdown format + link check"; the formatting language is "Markdown" (proper noun).
🔤 Proposed capitalization fix
- 3. **Run the validation gate** after each sync (markdown format + link check + skill `bin/` + 3. **Run the validation gate** after each sync (Markdown format + link check + skill `bin/`🤖 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 `@internal/contributor-info/agent-workflow-adoption.md` at line 117, In the validation gate section on line 117, locate the phrase "markdown format + link check" and capitalize the "m" in "markdown" to "Markdown" since it is a proper noun referring to the Markdown formatting language. Update the text from "markdown format" to "Markdown format" to follow proper noun capitalization conventions.
16-16: ⚡ Quick winAdd language identifier to the bash code block.
Line 16's fenced code block contains
git subtreeandlncommands but lacks a language identifier. Addingbashenables syntax highlighting and satisfies markdownlint MD040.🔤 Proposed fix
- 3. **Expose skills to Claude Code** (if the repo uses it): + 3. **Expose skills to Claude Code** (if the repo uses it): - ```bashAlso applies to: 40-40
🤖 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 `@internal/contributor-info/agent-workflow-adoption.md` at line 16, The fenced code blocks in the file are missing language identifiers which prevents syntax highlighting and violates markdownlint MD040. Add the bash language identifier to the opening fence of the code blocks containing git subtree and ln commands. Specifically, change the opening triple backticks to include bash as the language specifier (by adding bash immediately after the opening backticks on the same line). Apply this fix to both instances mentioned, including the one around line 16 and the one around line 40.
🤖 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 @.agents/skills/update-changelog/SKILL.md:
- Line 169: The markdown at line 169 contains a code span with a trailing space
that violates markdownlint rule MD038. Rephrase the sentence to convey that
users should start with a dash followed by a space, but structure it so the
trailing space is not included within the backticks of the code span. Consider
restructuring the text to clearly describe the dash-space pattern without
embedding the space character itself inside the code formatting.
- Around line 334-339: The grep command in step 4 uses a literal placeholder
`grep "PR XXX"` which cannot be executed as written. Replace the `PR XXX`
placeholder with a variable reference or concrete example showing users should
substitute the actual PR number (for example, use `grep "PR ${{
github.event.pull_request.number }}"` or similar notation to indicate where the
real PR number should be inserted). This will make the instruction copy-pastable
and clearly indicate that users need to substitute the actual PR number into the
command.
In @.agents/workflows/pr-processing.md:
- Around line 994-995: Step 9 in the pr-processing.md workflow currently allows
deferring changelog updates by documenting a reminder to run `/update-changelog`
before release, but this contradicts the merge-blocking treatment of missing
changelog entries elsewhere in the workflow. Modify step 9 to enforce that
user-visible changes must have their changelog entries updated immediately
before merge, or alternatively require an explicit maintainer waiver that must
be documented and approved. Remove the option to proceed with only a deferred
changelog reminder.
---
Nitpick comments:
In
`@docs/superpowers/specs/2026-06-18-portable-agent-workflows-subtree-design.md`:
- Line 112: Capitalize "markdown" to "Markdown" in two locations within the
document since Markdown is the proper noun name of the formatting language. On
line 112, change "markdown format" to "Markdown format". On line 156, change
"markdown links" to "Markdown links". Both instances need the first letter of
the word capitalized to correctly reference the proper noun.
In `@internal/contributor-info/agent-workflow-adoption.md`:
- Line 117: In the validation gate section on line 117, locate the phrase
"markdown format + link check" and capitalize the "m" in "markdown" to
"Markdown" since it is a proper noun referring to the Markdown formatting
language. Update the text from "markdown format" to "Markdown format" to follow
proper noun capitalization conventions.
- Line 16: The fenced code blocks in the file are missing language identifiers
which prevents syntax highlighting and violates markdownlint MD040. Add the bash
language identifier to the opening fence of the code blocks containing git
subtree and ln commands. Specifically, change the opening triple backticks to
include bash as the language specifier (by adding bash immediately after the
opening backticks on the same line). Apply this fix to both instances mentioned,
including the one around line 16 and the one around line 40.
🪄 Autofix (Beta)
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: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 3f9741e9-584e-4158-a0a8-d1f317f4af85
📒 Files selected for processing (20)
.agents/bin/agent-workflows-sync.agents/skills/address-review/SKILL.md.agents/skills/adversarial-pr-review/SKILL.md.agents/skills/autoreview/SKILL.md.agents/skills/evaluate-issue/SKILL.md.agents/skills/plan-pr-batch/SKILL.md.agents/skills/post-merge-audit/SKILL.md.agents/skills/pr-batch/SKILL.md.agents/skills/run-ci/SKILL.md.agents/skills/triage/SKILL.md.agents/skills/update-changelog/SKILL.md.agents/skills/verify-pr-fix/SKILL.md.agents/skills/verify/SKILL.md.agents/workflows/address-review.md.agents/workflows/continuous-evaluation-loop.md.agents/workflows/post-merge-audit.md.agents/workflows/pr-processing.mdAGENTS.mddocs/superpowers/specs/2026-06-18-portable-agent-workflows-subtree-design.mdinternal/contributor-info/agent-workflow-adoption.md
|
Clean, well-scoped Phase 1. The design is sound — seam model, three-transform taxonomy, and phased gating are all the right choices. The fidelity preservation argument in the design spec is unusually thorough. Findings below by priority. Medium — executable placeholder in address-review SKILL.md address-review/SKILL.md now has a code block an agent may copy and run that contains the literal string Medium — sync script misfires during Phase 1 The sync script detects add-vs-pull by checking whether commits exist for .agents/ — but in Phase 1 .agents/ was added as normal commits, not a git subtree squash. Running the script now would hit the pull branch and fail because git subtree cannot find the squash-merge ancestor. A note in the script (or checking the squash-commit message for git-subtree-dir instead) would prevent confusing failures. See inline comment. Minor — || true on UPSTREAM commit silences real failures The Minor — adoption guide references not-yet-existing upstream The guide's step 2 shows Positive notes: seam as single resolution point is much cleaner than scattered hardcoding; taxonomy and Pro RSpec note moving to AGENTS.md is correct; the post-merge-audit fingerprint template replacing a hardcoded example is a nice detail. Generated with Claude Code |
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
|
Codex batch handoff for Status: deferred / not pushed. Current remote PR head: What was handled locally:
Validation evidence from the worker:
Remaining blocker:
Next action:
|
Design for making the .agents/ skills and workflows repo-agnostic so they can be shared across ShakaCode flagship repos via git subtree and kept updated conflict-free, with all per-repo differences isolated to a named AGENTS.md "Agent Workflow Configuration" section (seam). Covers: architecture, the seam (Model A), the three-transform separation rule, shared-vs-repo-local skill classification, sync mechanics, fidelity preservation with a dry-run gate, and the three-phase rollout. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Consolidate the repo-specific tokens the portable .agents/ skills and workflows resolve against — base branch, pre-push local validation, CI change detector, hosted-CI trigger/labels, benchmark labels, follow-up prefix, changelog, lint/format, approval-exempt categories, and coordination backend — into one named section. This is the per-repo seam: making the shared workflow files repo-agnostic lets them point here instead of hardcoding react_on_rails commands, so the same files can be shared across repos via git subtree. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Extend the Agent Workflow Configuration seam with the remaining tokens the genericized .agents/ files resolve against: merge ledger, docs checks, tests, build/type checks, review gate, local-validation --fast and broad-suite modes, and changelog version-stamping. Relocate two pieces of react_on_rails-specific knowledge out of the shared skills into AGENTS.md so the shared files stay repo-agnostic: the changelog classification taxonomy (under Changelog) and the Pro RSpec UTF-8 encoding workaround (under Testing). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Rewrite the shared agent skills and workflows so they carry only portable workflow logic and resolve every repo-specific command, branch, label, path, and policy through AGENTS.md -> Agent Workflow Configuration. This lets the same .agents/ tree be shared byte-identical across repos via git subtree. All workflow structure, ordering, gates, and safety rules are preserved verbatim; only concrete react_on_rails tokens/subsystems became seam references (bin/ci-local, script/ci-changes-detector, +ci-* commands, hosted-CI/benchmark labels, Follow-up: prefix, CHANGELOG path, script/pr-merge-ledger, and Pro/RSC/Shakapacker domain examples). The agent-coord coordination backend is kept by name since the seam documents it. stress-test stays react_on_rails- specific and is excluded from the shared set. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…lper Rewrite internal/contributor-info/agent-workflow-adoption.md around the shared- upstream + git-subtree + AGENTS.md-seam model, replacing the copy-then-customize- in-place model that conflicts on every update. Adds the Agent Workflow Configuration seam template adopters fill in, the shared-vs-repo-local skill split, and the keep-updated flow. Add .agents/bin/agent-workflows-sync: vendors the shared .agents/ tree on first run and pulls updates afterward via git subtree --squash, recording the synced upstream SHA in .agents/UPSTREAM. Activates once the Phase 2 upstream (shakacode/agent-workflows) exists. Point AGENTS.md at the rewritten guide. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
justin808
force-pushed
the
jg-conductor/transfer-pr-batch-skills
branch
from
dcf3135 to
00c3430
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 00c34301e9
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Code Review - PR 4121: Share agent workflows across repos via subtree (Phase 1)OverviewWell-structured Phase 1 that correctly identifies the problem (skills entangled with repo-specific tokens) and provides a clean solution. The seam pattern -- all repo-specific values isolated to a named AGENTS.md section, shared files staying byte-identical -- is the right design for conflict-free subtree pulls. Validated findings:
1.
|
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 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
`@docs/superpowers/specs/2026-06-18-portable-agent-workflows-subtree-design.md`:
- Around line 1-10: The documentation file is currently located in a
non-standard directory structure that violates OSS documentation guidelines.
Move the file to the correct location under the OSS documentation directory
following the established structure, ensuring it is placed in an appropriate
subdirectory (such as specs/ if it exists, or another relevant category) under
the OSS docs hierarchy rather than in the superpowers directory at the root
level.
🪄 Autofix (Beta)
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: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: d7e580f8-b6d5-4881-88f2-e74c275ce952
📒 Files selected for processing (20)
.agents/bin/agent-workflows-sync.agents/skills/address-review/SKILL.md.agents/skills/adversarial-pr-review/SKILL.md.agents/skills/autoreview/SKILL.md.agents/skills/evaluate-issue/SKILL.md.agents/skills/plan-pr-batch/SKILL.md.agents/skills/post-merge-audit/SKILL.md.agents/skills/pr-batch/SKILL.md.agents/skills/run-ci/SKILL.md.agents/skills/triage/SKILL.md.agents/skills/update-changelog/SKILL.md.agents/skills/verify-pr-fix/SKILL.md.agents/skills/verify/SKILL.md.agents/workflows/address-review.md.agents/workflows/continuous-evaluation-loop.md.agents/workflows/post-merge-audit.md.agents/workflows/pr-processing.mdAGENTS.mddocs/superpowers/specs/2026-06-18-portable-agent-workflows-subtree-design.mdinternal/contributor-info/agent-workflow-adoption.md
✅ Files skipped from review due to trivial changes (3)
- .agents/skills/triage/SKILL.md
- .agents/skills/verify-pr-fix/SKILL.md
- .agents/skills/autoreview/SKILL.md
🚧 Files skipped from review as they are similar to previous changes (7)
- .agents/workflows/address-review.md
- .agents/workflows/continuous-evaluation-loop.md
- .agents/skills/plan-pr-batch/SKILL.md
- .agents/bin/agent-workflows-sync
- .agents/workflows/post-merge-audit.md
- AGENTS.md
- .agents/workflows/pr-processing.md
Bugbot couldn't run - usage limit reachedBugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit. A user or team admin can review and increase usage limits in the Cursor dashboard. (requestId: serverGenReqId_5091fe2a-358d-42da-b757-af187d2de300) |
justin808
changed the title
|
+ci-run-hosted |
Hosted CI RequestedTriggered 9 workflow(s) for View progress in the Actions tab. |
Code Review: Share agent workflows via installed skills + repo seamOverviewThis PR introduces a portability seam so shared agent skills/workflows stop hardcoding React on Rails–specific commands, labels, and paths. The concrete design has three main parts:
The approach is sound and well-designed. A few observations follow. Strengths
Issues and SuggestionsMinor code issues1. In 2. Seam validator scans repo-local and shared-root files with different-looking path formats A finding from a shared-root file shows the path relative to the shared root (e.g. 3. At the compare-link example: This is inside a Markdown code block, so 4. The old skill listed concrete commands ( Missing test coverage5. Symlinked shared-root deduplication is untested If SecurityNo concerns. All external data comes from SummaryWell-designed, low-risk change. The portability seam architecture is the right approach. All identified issues are minor (documentation gaps, one UX issue in abstracted prose, one literal-value-in-example issue, one missing edge-case test). None block merge. |
Address-review summaryScan scope: current-head optional review feedback on 2026-06-22 for head Mattered
Optional
Skipped
Shared source repo has been mirrored through |
Code ReviewOverviewThis PR introduces a repo seam ( The design is sound: the seam is intentionally human-readable (AGENTS.md is already the canonical agent policy), the Strengths
IssuesMinor logic redundancy in
|
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 68db6f134e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| 4. **Keep repo-local skills local.** Add only repo-specific skills, tiny | ||
| compatibility launchers, or local validation helpers to the repo. Do not copy | ||
| shared workflow text into the repo unless the execution environment cannot | ||
| load user-installed skills. If an agent surface can load installed skill |
There was a problem hiding this comment.
For installed-skill-only adopters, this guidance says not to copy shared workflow text into the repo, but the installed skills still direct agents to repo-relative workflow files such as .agents/workflows/pr-processing.md and stop with UNKNOWN when those files are missing (for example in .agents/skills/pr-batch/SKILL.md). A repo following these lines can install the skills successfully but then $pr-batch has no local workflow file to follow, so either require local workflow copies/launchers or make the skills resolve the installed workflow location too.
Useful? React with 👍 / 👎.
| def update_fence_state(line, in_fence, fence_delimiter) | ||
| fence = line.match(/^ {0,3}(```|~~~)([[:alnum:]_-]*)(?:\s.*)?$/) |
There was a problem hiding this comment.
When a shared skill uses a valid Markdown fence of four or more backticks/tildes, this regex never enters fence state because it only recognizes exactly three delimiters. In that case an executable block like ````bash containing gh issue create --title "<follow-up prefix> ..." is treated as plain prose and the unresolved seam placeholder is not reported, so the seam doctor can pass an unusable installed workflow; accept 3+ delimiter characters and close only on a matching fence length.
Useful? React with 👍 / 👎.
|
simple test line |
Code Review -- PR 4121: Share agent workflows via installed skills + repo seamOverall: Solid architectural improvement. Moving from vendored copies to user-installed shared skills + repo seam is the right call -- it eliminates the sync-tax every adopting repo would otherwise pay. The seam-doctor tool is well-structured Ruby with good Minitest coverage (75 assertions across 28 tests), and the skill portability rewrites are clean mechanical changes. A few issues worth addressing before merge. Issues1. Encoding inconsistency -- crash risk on non-UTF-8 AGENTS.md
2. No test for invalid UTF-8 in AGENTS.md
3. REQUIRED_KEYS could silently diverge from the shared-repo canonical list The required-key list is hardcoded in both this repo-local seam-doctor and the Minor Notes
What is working wellThe fence-state machine handles titled fences, tilde fences, mismatched-closer non-close, 4-space-indented pseudo-fences, and the double-reporting guard for inline code inside executable fences -- all covered by dedicated tests. The design-doc rewrite (seam-first over subtree-first) is cleaner and easier to follow than what it replaces. |
|
|
||
| return ["missing AGENTS.md"] unless File.file?(agents_path) | ||
|
|
||
| config = parse_config(File.read(agents_path)) |
There was a problem hiding this comment.
File.read here uses Encoding.default_external, so a Latin-1 byte in AGENTS.md (e.g. a curly-quote) will raise Encoding::InvalidByteSequenceError and crash the tool instead of printing a clean FAIL.
The skill-file scanner already handles this correctly with File.binread(path).force_encoding("UTF-8").scrub on line 193. Suggest the same pattern here:
| config = parse_config(File.read(agents_path)) | |
| config = parse_config(File.binread(agents_path).force_encoding("UTF-8").scrub) |
| current_key && line.match?(/^\s{2,}\S/) && !line.match?(CONFIG_KEY_PATTERN) | ||
| end | ||
|
|
||
| def config_key_finished?(line) |
There was a problem hiding this comment.
The name config_key_finished? implies the method fires only when a key section is definitively over, but it returns true for any line that is not a continuation -- blank lines, prose paragraphs, even the section heading it inherited from extract_section. The logic is correct but the name misleads on first read. Consider non_continuation_line? or ends_continuation?.
| module AgentWorkflowSeamDoctor | ||
| SECTION = "Agent Workflow Configuration" | ||
| SECTION_HEADING = /^##\s+#{Regexp.escape(SECTION)}\s*$/ | ||
| REQUIRED_KEYS = [ |
There was a problem hiding this comment.
This list is duplicated in the shakacode/agent-workflows canonical copy. When upstream adds a required key, repos carrying only the local checker will silently miss it -- their check will pass while the shared-skill pack actually requires the new key. A comment here noting that this list must be kept in sync with the upstream canonical, and that adopters should validate with --shared against a fresh clone after any sync, would prevent quiet drift.
| end | ||
| end | ||
|
|
||
| def test_invalid_utf8_markdown_does_not_crash_scanner |
There was a problem hiding this comment.
This test covers the skill-file path (.agents/skills/example/invalid.md) but the AGENTS.md reader on line 72 of the script uses File.read, which is not scrubbed and will crash on a Latin-1 byte rather than returning a clean FAIL. A companion test here — writing a bad byte into AGENTS.md itself — would catch that gap:
def test_invalid_utf8_agents_md_does_not_crash
with_repo do |root|
File.binwrite(File.join(root, "AGENTS.md"), "## Agent Workflow Configuration\n\nLatin-1: \xE9\n")
out, status = run_doctor(root)
refute status.success?
assert_includes out, "FAIL"
end
end
Bugbot couldn't run - usage limit reachedBugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit. A user or team admin can review and increase usage limits in the Cursor dashboard. (requestId: serverGenReqId_ec189c58-a853-4133-a789-642eb7724ed6) |
## Summary - carry forward the post-merge #4121 seam-doctor/adoption fixes that landed on the closed branch after #4121 was squash-merged at `68db6f1` - teach `agent-workflow-seam-doctor` to scan 3+ backtick/tilde executable fences, reject too-short closers, accept same-character closers at least as long as the opener, reject info strings on closing fences, handle CRLF closers, and parse spaced info-string languages - clarify user-installed shared skill adoption: install `workflows/` with `skills/`, or keep repo-local workflow copies/launchers for skills that reference `.agents/workflows/...` - document the shared-pack status/upgrade path for Codex and Claude installs - keep the React on Rails compatibility copy aligned with `shakacode/agent-workflows@d38645b` ## Rationale #4121 created and referenced the public shared workflow repo, but two late P2 review findings arrived after the merged head. The shared repo already contains the fixes; this PR keeps the React on Rails compatibility copy and adoption docs in sync with the published pack. Current-head review on this follow-up also tightened the CommonMark closing-fence behavior, now fixed here and in the shared repo. The shared pack now also includes host-aware install/status/upgrade helpers inspired by the gstack upgrade flow: explicit status tokens, Codex/Claude host targets, network disclosure, rollback if a consumer seam validation fails, and preservation of unrelated user-installed agent files. Original #4121 review threads: - #4121 (comment) - #4121 (comment) ## Changelog Not user-visible; agent workflow docs/tooling only. ## Validation - `ruby .agents/bin/agent-workflow-seam-doctor-test.rb` -> 39 runs, 98 assertions, 0 failures - `.agents/bin/agent-workflow-seam-doctor --shared /Users/justin/codex/agent-workflows` -> PASS - `(cd /Users/justin/codex/agent-workflows && bin/validate)` -> PASS at `d38645b` - `git diff --check` in both `react_on_rails` and `agent-workflows` -> clean - `bin/ci-local --changed` -> docs-only, Docs Sidebar Check passed, no further CI needed - pre-commit hook -> trailing newlines, offline markdown links, Prettier passed - pre-push hook -> branch RuboCop no offenses; online markdown links 29 OK <!-- CURSOR_SUMMARY --> --- > [!NOTE] > **Low Risk** > Changes are limited to agent workflow tooling and internal documentation; no application runtime, auth, or user-facing product code paths are modified. > > **Overview** > Syncs the repo’s agent-workflow compatibility copy with post-#4121 fixes from `shakacode/agent-workflows`, focused on **seam validation** and **adoption docs**. > > **`agent-workflow-seam-doctor`** now parses Markdown code fences closer to CommonMark: 3+ backtick/tilde openers, closers must match character and be at least as long as the opener (shorter closers stay inside the fence), closing lines with info strings do not close a fence, CRLF closers work via `chomp`, and spaced info strings (e.g. ` ``` bash`) still mark executable fences. A large new test suite covers long fences, mismatched delimiters, and non-executable fenced content. > > **Docs/skills** broaden “Codex batch” wording to **agent / Codex / Claude** batches in `AGENTS.md`, `pr-batch`, and contributor guides. Adoption and design docs add **`agent-workflows-status`** and **`upgrade-agent-workflows`** for Codex and Claude hosts, stress installing **`workflows/`** alongside **`skills/`**, and link the shared pack’s installation/upgrade guide. > > <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit 924b4eb. Bugbot is set up for automated code reviews on this repo. Configure [here](https://www.cursor.com/dashboard/bugbot).</sup> <!-- /CURSOR_SUMMARY -->
…ck-comparison-doc * origin/main: Bump version to 17.0.0.rc.6 docs: fix dead undici link and silence flaky GitHub links in lychee check (#4165) Update changelog for 17.0.0.rc.6 (#4174) Reduce PR security preflight false positives for CI metadata (#4170) [codex] Document targeted agent coordination reads (#4166) Carry forward seam doctor follow-up fixes (#4171) Unskip Rspack RSC e2e tests on react-on-rails-rsc 19.2 (rc.3) (#4173) Revert "docs: add accessibility best-practices guide (RoR + RSC) (#4086)" docs: rsc-css render-blocking links + end-of-head cascade trap (#4138) (#4143) Fix RSC-safe locale default messages output (#4146) Share agent workflows via installed skills + repo seam (#4121) Codify degraded agent-coord batch fallback (#4161) [codex] Document flagship demo coordination (#4164) Enrich deferred-render RSC errors with the bundle diagnostic (#3475) (#4100)
…tion-path * origin/main: docs(agents): make completing an authorized merge the expected close-out (#4156) docs: add accessibility best-practices guide (RoR + RSC) (#3927) (#4179) Bump version to 17.0.0.rc.6 docs: fix dead undici link and silence flaky GitHub links in lychee check (#4165) Update changelog for 17.0.0.rc.6 (#4174) Reduce PR security preflight false positives for CI metadata (#4170) [codex] Document targeted agent coordination reads (#4166) Carry forward seam doctor follow-up fixes (#4171) Unskip Rspack RSC e2e tests on react-on-rails-rsc 19.2 (rc.3) (#4173) Revert "docs: add accessibility best-practices guide (RoR + RSC) (#4086)" docs: rsc-css render-blocking links + end-of-head cascade trap (#4138) (#4143) Fix RSC-safe locale default messages output (#4146) Share agent workflows via installed skills + repo seam (#4121) Codify degraded agent-coord batch fallback (#4161)
1 participant
What and why
The
pr-batchfamily and related agent workflows are mature, but the reusable parts were tangled with React on Rails-specific commands, labels, paths, and release policy. This PR makes the user/agent-installed shared skill model the default and uses a repo-localAGENTS.mdseam to supply concrete repo values.This avoids making every repo vendor a
.agents/subtree just to use the workflows. The seam is the important contract; repo-pinned copies can remain an optional fallback for environments that cannot load installed skills.Shared source repo:
shakacode/agent-workflows, published at initial commit50a6cfeand currently updated to304e4d3.Design doc:
internal/contributor-info/portable-agent-workflows-seam-design.md.What this PR does
## Agent Workflow ConfigurationtoAGENTS.md, the single named place shared skills resolve repo-specific values: base branch, validation, CI detector, hosted-CI trigger/labels, benchmark labels, follow-up prefix, changelog policy, lint/format, build/type/test, merge ledger, review gate, approval-exempt categories, and coordination backend.shakacode/agent-workflows, includingskills/,workflows/, installer/validation helpers, adoption docs, seam design, and a fixture-backedbin/validategate..agents/bin/agent-workflow-seam-doctorplus tests. It verifies required seam keys and catches unresolved seam placeholders embedded in executable snippets.Not in this PR
control-plane-flow,shakapacker,shakaperf, etc.).origin/mainexample in shared workflow prose. The seam checker covers the contract and the highest-risk unresolved seam placeholders; broader base-ref cleanup can be a follow-up.Validation
Shared repo:
bin/validatein/Users/justin/codex/agent-workflows(latest run after review fixes)bin/install-agent-workflows --target <tmp>/copybin/install-agent-workflows --target <tmp>/symlink --mode symlinkhttps://github.com/shakacode/agent-workflows, public, default branchmain, head304e4d3React on Rails PR:
ruby .agents/bin/agent-workflow-seam-doctor-test.rb(28 runs, 75 assertions).agents/bin/agent-workflow-seam-doctor.agents/bin/agent-workflow-seam-doctor --shared /Users/justin/codex/agent-workflowsruby .agents/skills/pr-batch/bin/agent-coord-bounded-test.rblychee --config .lychee.toml AGENTS.md internal/contributor-info/agent-workflow-adoption.md internal/contributor-info/portable-agent-workflows-seam-design.mdbin/ci-local --changedgit diff --checkFull
bin/check-linkswas attempted after cache refresh but the whole-repo lychee crawl stayed silent for roughly four minutes, so I stopped it and ran the focused changed-file lychee command above successfully.No user-visible runtime change; no
CHANGELOG.mdentry.Note
Low Risk
Documentation and agent-tooling only; no runtime product code. Risk is mainly agents following wrong commands if the seam is misconfigured—mitigated by the new seam-doctor gate.
Overview
Introduces a repo seam model so agent skills can ship from a shared install (
shakacode/agent-workflows) while each repo supplies concrete commands, labels, and paths throughAGENTS.md→ Agent Workflow Configuration.Adds
.agents/bin/agent-workflow-seam-doctor(plus Minitest coverage) to require that seam section and its keys, and to fail on unresolved<…>placeholders inside executable markdown (skills/workflows, including optional--sharedroots).Refactors
.agents/skills/*and.agents/workflows/*to drop React-on-Rails–specific literals (bin/ci-local,CHANGELOG.md,ready-for-hosted-ci, hardcoded helper paths) in favor of seam lookups,_*_SKILL_DIRoverrides for bin helpers, and shell vars such asFOLLOW_UP_PREFIXthat error if unset. Verification, CI, changelog, review, and batch flows now describe behavior generically while still defaulting to repo-local paths in this checkout.Reviewed by Cursor Bugbot for commit 68db6f1. Bugbot is set up for automated code reviews on this repo. Configure here.
Merge Criteria
Current head:
68db6f134ec5528d1fc543190797219095144fa7.required-pr-gateto pass before merge.68db6f134ec5528d1fc543190797219095144fa7; merge requires zero unresolved current threads.68db6f134ec5528d1fc543190797219095144fa7. The hosted-CI bot status comment is treated as expected repository automation, not untrusted issue content to execute.