Skip to content

修正 agent skills 的 B 方案邊界與 worktree env 規則 - #82

Merged
monkey1sai merged 2 commits into
mainfrom
agent-skills-boundary-fix
May 21, 2026
Merged

monkey1sai merged 2 commits into
mainfrom
agent-skills-boundary-fix

Conversation

@monkey1sai

@monkey1sai monkey1sai commented May 21, 2026 •

Copy link
Copy Markdown
Owner

變更摘要

  • 將 tracked Claude workflow skills 對齊 AGENTS.md 的 B 方案邊界:bim-review-coordinator 作為唯一外部 IFC-ready intake / callback outbox / session control plane,bim-streaming-server 作為 internal-only IFC→USDC authority,web-viewer-sample 作為 browser client。
  • 移除 workflow 指引中把 _worker、_bim-control、_conversion-service、_s3_storage 當作 current runtime / startup / smoke dependency 的範例,改成 retired / historical / test-double context。
  • 更新 worktree provisioning env copy 規則,只掃描 current core service .env,並同步 docs/agent-tooling/opsx-worktree-provision.md。
  • 將 PR/debug 範例改指向目前的 bim-review-coordinator/src/services/callbackOutbox.ts / deliverPending callback outbox 路徑。

驗證

  • git diff --check passed(只有 LF→CRLF warning,沒有 whitespace error)
  • npx gitnexus detect-changes --scope staged --repo AI-BIM-governance → No changes detected.(本次為 docs / agent skills,未命中 indexed runtime symbols)
  • forbidden old-runtime pattern scan passed;剩餘 retired service references 都是明確 historical / retired / test-double context
  • GitHub compare 確認 branch ahead 1 commit,5 個檔案皆為小範圍 diff

注意

  • .codex/skills/project-visual-planning 已在新 worktree 的 ignored local copy 中同步修正,但依 AGENTS.md policy,.codex/skills/ 預設不提交,所以未納入此 PR。
  • 本機 gh token / HTTPS git push auth 無效,因此遠端 branch 與 PR 是透過 GitHub connector 建立。

Summary by CodeRabbit

  • Documentation
    • Refined service boundary rules and testing procedures in task verification workflows
    • Updated worktree provisioning configuration to exclude retired services
    • Enhanced PR review gate procedures with improved debugging workflow examples
    • Clarified git command execution context requirements

Review Change Stack

Copilot AI review requested due to automatic review settings May 21, 2026 03:31
@coderabbitai

coderabbitai Bot commented May 21, 2026 •

Copy link
Copy Markdown
Contributor

Warning

Rate limit exceeded

@monkey1sai has exceeded the limit for the number of commits that can be reviewed per hour. Please wait 52 minutes and 8 seconds before requesting another review.

You’ve run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After the wait time has elapsed, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout.

Please see our FAQ for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 18f457f7-d0de-4468-b4d0-e3efdbc32cb7

📥 Commits

Reviewing files that changed from the base of the PR and between fce0fbd and 6e9b51a.

📒 Files selected for processing (2)
  • .claude/skills/apply-and-verify/SKILL.md
  • docs/agent-tooling/opsx-worktree-provision.md
📝 Walkthrough

Walkthrough

Skills and documentation updated to retire legacy services from operational contexts. Bounded-service rules and .env provisioning policies now exclude retired services. Per-service testing commands, debug examples, and design documentation aligned to reflect active service implementations and worktree provisioning boundaries.

Changes

Operational Skills and Documentation Refresh

Layer / File(s) Summary
Legacy service exclusion from provisioning and boundaries
.claude/skills/apply-and-verify/SKILL.md, .claude/skills/opsx-worktree-provision/SKILL.md
Bounded-service rules and .env copy policies updated to explicitly exclude retired services (_worker, _bim-control, _conversion-service, _s3_storage) from task implementation scope and worktree provisioning, limiting copies to active services (bim-review-coordinator, bim-streaming-server, web-viewer-sample).
Per-service testing commands and debug loop examples
.claude/skills/apply-and-verify/SKILL.md, .claude/skills/gitnexus-blast-radius/SKILL.md, .claude/skills/pr-review-gate/SKILL.md
Step 3 focused-test invocations expanded to cover external contracts, coordinator, streaming-server conversion authority, and web-viewer components individually; gh pr create execution context clarified; and debug loop example replaced with callback retry path scenario using bim-review-coordinator.
Design documentation alignment with .env copy changes
docs/agent-tooling/opsx-worktree-provision.md
opsx-worktree-provision design document updated to reflect the new .env copy scan list (excluding retired services) and to align the manifest env_copied.copied example with the active service list.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Possibly related PRs

  • monkey1sai/AI-BIM-governance#36: Introduced the initial skill definitions and operational procedures that are now being refined to retire legacy services.
  • monkey1sai/AI-BIM-governance#53: Previously updated opsx-worktree-provision skills and design documentation; this PR further refines .env copy rules and extends service retirement scope.

Poem

🐰 Old services fade to history's care,
As worktrees bloom with active air,
Tests per service, clean and bright,
Retired paths archived right! 🌿

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately describes the main changes: correcting agent skills' B-plan boundaries and worktree env rules, which aligns with the PR's core objectives of realigning service boundaries and updating .env copying rules.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.

✏️ Tip: You can configure your own custom pre-merge checks in the settings.

✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch agent-skills-boundary-fix

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.

❤️ Share

Comment @coderabbitai help to get the list of available commands and usage tips.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 2

🧹 Nitpick comments (1)
.claude/skills/apply-and-verify/SKILL.md (1)

71-73: ⚡ Quick win

Scope the external tests to contract/fake paths explicitly.

Line 72 currently runs pytest tests -x, which is broader than the “focused tests” intent and can pull in unrelated suites. Prefer targeting only contract/fake directories.

Suggested doc fix
-# external platform contracts + test-only fakes
-!`cd "<cwd_hint>" && python -m pytest tests -x`
+# external platform contracts + test-only fakes
+!`cd "<cwd_hint>" && python -m pytest tests/contracts tests/fakes -x`
🤖 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 @.claude/skills/apply-and-verify/SKILL.md around lines 71 - 73, Replace the
broad test invocation string `cd "<cwd_hint>" && python -m pytest tests -x` with
a scoped pytest call that only runs the contract and fake test folders; locate
that exact command in the file and change it so pytest is invoked against the
specific directories for contracts and fakes (preserving the `-x` flag and the
cwd change), ensuring unrelated test suites are not executed.
🤖 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 @.claude/skills/apply-and-verify/SKILL.md:
- Line 138: Fix the typo "呠叫" on the note line referencing `gh pr create` so the
operator instruction is clear; locate the markdown line containing the
backticked `gh pr create` and `<cwd_hint>` and replace "呠叫" with the correct
term (e.g., "呼叫") so the sentence reads that the command can be called from the
main worktree or `<cwd_hint>`.

In `@docs/agent-tooling/opsx-worktree-provision.md`:
- Around line 125-126: Update the manifest sample (env_copied.copied) to match
Step 6 scan targets: either add the missing third service .env entry shown in
Step 6 (so the file lists ".env", "bim-review-coordinator/.env" and the third
active-service path) or clearly label env_copied.copied as a partial example
(e.g., "partial example — not all scan targets listed") so operators know it
doesn't include every active-service entry; reference the manifest file name
env_copied.copied and the Step 6 scan targets when making the change.

---

Nitpick comments:
In @.claude/skills/apply-and-verify/SKILL.md:
- Around line 71-73: Replace the broad test invocation string `cd "<cwd_hint>"
&& python -m pytest tests -x` with a scoped pytest call that only runs the
contract and fake test folders; locate that exact command in the file and change
it so pytest is invoked against the specific directories for contracts and fakes
(preserving the `-x` flag and the cwd change), ensuring unrelated test suites
are not executed.
🪄 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: defaults

Review profile: CHILL

Plan: Pro

Run ID: acec471f-bf65-48c1-aa9e-55699898b24e

📥 Commits

Reviewing files that changed from the base of the PR and between fe29121 and fce0fbd.

📒 Files selected for processing (5)
  • .claude/skills/apply-and-verify/SKILL.md
  • .claude/skills/gitnexus-blast-radius/SKILL.md
  • .claude/skills/opsx-worktree-provision/SKILL.md
  • .claude/skills/pr-review-gate/SKILL.md
  • docs/agent-tooling/opsx-worktree-provision.md

Comment thread .claude/skills/apply-and-verify/SKILL.md Outdated
Comment thread docs/agent-tooling/opsx-worktree-provision.md

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR updates the tracked agent skills and operator documentation to align with the clarified B-scheme service boundaries and current worktree provisioning rules (including removing retired services from “current runtime” examples).

Changes:

  • Update worktree .env provisioning rules to scan/copy only current core services (excluding retired _bim-control, _worker, _conversion-service, _s3_storage).
  • Refresh skill/debug examples to point to the current callback outbox path (bim-review-coordinator/src/services/callbackOutbox.ts / deliverPending).
  • Reframe retired services as historical/test-double context in workflow guidance.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file
File Description
docs/agent-tooling/opsx-worktree-provision.md Updates env scan/copy targets and documents retired-service exclusion.
.claude/skills/pr-review-gate/SKILL.md Updates debug-loop example to target coordinator callback outbox retry path.
.claude/skills/opsx-worktree-provision/SKILL.md Aligns skill’s env copy behavior with the updated core-service-only rule.
.claude/skills/gitnexus-blast-radius/SKILL.md Updates reviewer-comment→debug-target example to the callback outbox path.
.claude/skills/apply-and-verify/SKILL.md Updates bounded-service boundary description and the focused verification commands.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread docs/agent-tooling/opsx-worktree-provision.md
Comment thread .claude/skills/apply-and-verify/SKILL.md Outdated
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants