docs(skills): 新增三技能閉環自動化 14-step workflow skills - #36
Conversation
依「三技能閉環自動化工作流設計研究報告」PDF，落地 7 個 Claude Code skills （1 orchestrator + 6 worker），覆蓋 OpenSpec change lifecycle 完整 14 步驟： - closed-loop-orchestrator：串接 Phase A-F，merge/archive 前停下等使用者同意 - change-id-resolve：解析下一個 active change-id，套用 NoSuccessorWhilePredecessorOpen gate - openspec-explore-twice：強制兩輪 explore，open questions 不可遺留 - gitnexus-blast-radius：pre-change impact + post-change detect_changes - apply-and-verify：apply + 四層驗證 (openspec / focused tests / git diff / detect_changes) - pr-review-gate：CI checks + reviewer comments + GitNexus debug loop + 人工 merge gate - archive-and-closeout：archive branch + spec sync + roadmap sync + cleanup .gitignore 同步調整：碰出這 7 個 skill 目錄為 tracked，其餘 .claude/ 維持 ignored。
📝 WalkthroughWalkthroughThis PR introduces a complete multi-phase workflow system for managing OpenSpec-driven changes. Seven new Claude skills define the specification exploration, risk analysis, implementation verification, PR review gating, archive/closeout, and change resolution phases. The ChangesOpenSpec Workflow Orchestration
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 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 |
Code Review Summary（五軸評估）Verdict: COMMENT only（無 blocking issue，2 個建議於下次迭代採納） PR 規模：8 files / +1023 lines / -1 line。7 個 SKILL.md（103–192 lines 之間）+ ✅ Correctness（正確性）
✅ Readability（可讀性）
✅ Architecture（架構）
✅ Security（安全性）
✅ Performance（效能）
💡 建議（非 blocking，下次迭代採納）
✅ Looks Good（亮點）
結論本 PR 為 tooling layer 變更（不動產品程式碼、specs、roadmap），risk_level LOW，建議 merge 後立即跑一次 🤖 Review by Claude Code（Opus 4.7） |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 14
🧹 Nitpick comments (2)
.claude/skills/archive-and-closeout/SKILL.md (1)
22-24: 💤 Low valueConsider adding language specifiers to code blocks.
Multiple fenced code blocks lack language specifiers. Adding hints like
bash,markdown, ortextwould improve documentation quality and resolve linting warnings.Also applies to: 34-36, 42-44, 72-76, 82-89, 93-103, 141-143, 155-160, 175-177
🤖 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/archive-and-closeout/SKILL.md around lines 22 - 24, Several fenced code blocks (e.g., the blocks containing `!`git switch main`` and `!`git pull origin main --ff-only`` and other blocks noted at ranges 34-36, 42-44, 72-76, 82-89, 93-103, 141-143, 155-160, 175-177) are missing language specifiers; update each triple-backtick fence to include an appropriate language hint like ```bash for shell commands or ```text/markdown for plain text so linters and renderers can parse them correctly, ensuring each fence that contains shell commands (`git ...`, `az ...`, etc.) uses ```bash and other examples use a suitable specifier..claude/skills/pr-review-gate/SKILL.md (1)
20-22: 💤 Low valueConsider adding language specifiers to code blocks.
Multiple fenced code blocks are missing language specifiers. While these blocks contain command examples rather than executable code, adding language hints (e.g.,
bash,text,yaml) would improve documentation clarity and satisfy linting tools.Also applies to: 30-32, 44-46, 61-63, 71-81, 89-91
🤖 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/pr-review-gate/SKILL.md around lines 20 - 22, The fenced code blocks in .claude/skills/pr-review-gate/SKILL.md (e.g., the block containing the gh pr view command) are missing language specifiers; update each triple-backtick fence for those examples (including the blocks at the other noted ranges) to include an appropriate hint such as bash, text, or yaml (for example change ``` to ```bash or ```text) so linters and readers get correct syntax highlighting and semantics; locate the blocks by the shown example command `gh pr view <pr-number> --json number,title,state,mergeable,mergeStateStatus,reviewDecision,statusCheckRollup,labels,reviews` and apply the same change to the other listed blocks.
🤖 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:
- Around line 9-10: The verification contract in SKILL.md declares "type check →
lint → affected unit tests → integration / E2E" but does not enforce type-check
and lint in the Step 3 gate; update the document and pipeline notes so that the
Step 3 "OpenSpec validate + tests + diff check + detect-changes" block first
runs and fails on static/type checks (e.g., add explicit commands for Python
services: python -m mypy . and python -m ruff check .; and for frontend: npm run
typecheck and npm run lint) and require those to pass before running
unit/integration tests; ensure the text references the verification order and
that failing type/lint short-circuits the rest of Step 3.
- Around line 37-44: Several fenced code blocks in the SKILL.md doc are
unlabeled (triggering markdownlint MD040); update each unlabeled ``` block to
include the appropriate language tag (e.g., use ```text for directory/listing
blocks like the "openspec/changes/<change-id>/ ..." block and for PR body
templates, and use ```bash for command lines such as `openspec validate
<change-id> --strict`, `cd _worker && python -m pytest ...`, `git diff --check`,
`gitnexus detect-changes --scope staged`, `git push -u origin
codex/openspec/<change-id>`, and the `gh pr create \` block) so every fenced
block is explicitly typed and markdownlint MD040 is resolved.
In @.claude/skills/archive-and-closeout/SKILL.md:
- Around line 70-76: Replace the CLI-style invocation with the project's
function-style call: change the `gitnexus detect-changes --scope staged` line to
the underscore form `gitnexus_detect_changes()` (or the explicit call
`gitnexus_detect_changes(repo="...", scope="staged")`) so it matches the
documented usage patterns and verifies staged changes before commit; update any
surrounding examples/snippets to use the function name `gitnexus_detect_changes`
consistently.
In @.claude/skills/change-id-resolve/SKILL.md:
- Line 4: The allowed-tools list on the SKILL.md header currently lacks
permission for the ls command used later (see Step 4); update the allowed-tools
entry (the line beginning with "allowed-tools:") to include Bash(ls*) so that
Bash can execute ls at runtime and unblock the skill; ensure the same addition
is applied where the header repeats (noted at lines referenced in the review).
- Line 9: Links to AGENTS.md, CLAUDE.md and docs/... in SKILL.md are using
incorrect relative paths and likely broken; update each Markdown link (e.g.,
"AGENTS.md", "CLAUDE.md", any "docs/..." links) to use the correct repo-relative
path from the current document (for example prefix with ../../../ to reach the
repository root) or replace them with absolute repository URLs, and verify all
occurrences in the file are fixed (including other instances of AGENTS.md,
CLAUDE.md, and docs/...).
- Around line 21-23: The markdown fences in SKILL.md are missing language
identifiers which triggers markdownlint MD040; update each fenced code block
(the backtick blocks shown around `git status --porcelain` and the other
occurrences at the ranges called out) to include a language tag (use bash) so
they read as fenced blocks like ```bash; ensure you apply this change to all
listed occurrences (lines referenced in the comment: the block at the example
plus the ones at 29-32, 44-46, 56-58, 68-70) so the linter stops flagging MD040.
- Around line 34-40: Update the step that reads the roadmap so it explicitly
fetches the file from origin/main instead of the worktree: replace the implicit
instruction to "讀 docs/plans/AI-BIM-governance-saas-roadmap-2026-05.md" with a
command that reads the file from the remote branch (e.g., use git show
origin/main:docs/plans/AI-BIM-governance-saas-roadmap-2026-05.md) and then
search that output for the latest "YYYY-MM-DD 更新（... active change）" or keywords
like "active change" / "下一個 worker risk burn-down" to ensure change_id
resolution uses origin/main content.
In @.claude/skills/closed-loop-orchestrator/SKILL.md:
- Line 5: The allowed-tools list does not permit the git commands required by
the "pull rebase" step used by the continue-existing flow; update the
allowed-tools entry (the "allowed-tools:" line) to include git pull* and/or git
rebase* (or a broader git* pattern) so the declared "pull rebase" step and the
continue-existing phase can execute, ensuring the pattern matches the existing
git commands like "git pull --rebase" used in the workflow.
- Around line 25-27: Add language identifiers to the fenced code blocks in
.claude/skills/closed-loop-orchestrator/SKILL.md to satisfy markdownlint MD040:
tag plain skill invocation blocks with "text" (e.g. the blocks containing
"/change-id-resolve", "/openspec-explore-twice <change-id>",
"/gitnexus-blast-radius pre-change <symbol1,symbol2,...>", "/apply-and-verify
<change-id>", "/pr-review-gate <pr-number>", "/archive-and-closeout
<change-id>") and tag the shell command block containing backticked git/gh
commands with "bash"; update each triple-backtick opening fence accordingly for
the occurrences around lines referenced (also at 40-42, 54-56, 66-68, 83-85,
97-99, 123-127).
- Line 3: Update the description in SKILL.md to correct the skill-count wording:
replace 「三技能」 with 「七技能」 (or "七項技能") so the line accurately states that this
orchestrator depends on seven skills in this PR/stack; ensure the rest of the
sentence remains unchanged (the phrase describing the 14-step closed loop and
the pause-before-irreversible phases should be preserved).
In @.claude/skills/gitnexus-blast-radius/SKILL.md:
- Around line 21-23: The markdown contains unlabeled fenced code blocks with
shell commands (e.g., the backticked lines containing gitnexus analyze
--embeddings --skills --skip-agents-md, gitnexus impact --target <symbol>
--direction upstream, gitnexus detect-changes --scope staged, and git diff
--name-only --cached) which triggers MD040; update each fenced code block around
these commands to include the language label "bash" (i.e., replace ``` with
```bash) at every occurrence noted (including the other locations mentioned) so
the code fences are properly labeled for markdownlint.
- Around line 99-103: The fallback wording is inconsistent: the prose mentions
"git diff --name-only" while the actual fallback command uses "git diff
--name-only --cached"; update the SKILL.md fallback text so both references
match by replacing the staged-only reference with "git diff --name-only
--cached" (or vice versa if you intentionally want unstaged files) so the
fallback evidence only includes staged files; adjust the line that currently
reads the unstaged command to the staged-only form to match the command used
later.
In @.claude/skills/openspec-explore-twice/SKILL.md:
- Around line 20-27: The unlabeled fenced code blocks showing the directory tree
(the block containing "openspec/changes/<change-id>/ ├── proposal.md ...") and
the command block containing the command invocation starting with "!`openspec
validate <change-id> --strict`" need explicit languages to satisfy MD040 and
improve readability; change the tree block fence from ``` to ```text and change
the command block fence from ``` to ```bash so the tree uses a plain-text fence
and the command uses a bash shell fence respectively.
In @.claude/skills/pr-review-gate/SKILL.md:
- Around line 28-65: Update the workflow text to separate CI failures from
reviewer-requested changes: change the Step 2 rule for "fail > 0" to route to a
new "CI Failure Resolution Loop" (describe: fix code/tests, re-run CI, then
return to Step 2) and add a clarifying note that CI failures do not enter the
"Debug Loop (Step 4)"; leave Step 4 ("Debug Loop") explicitly scoped to handling
`REQUEST_CHANGES` comments (summarize comment → call `/gitnexus-blast-radius
post-change` → apply-and-verify → re-push → back to Step 2) so readers can
clearly distinguish the two remediation paths.
---
Nitpick comments:
In @.claude/skills/archive-and-closeout/SKILL.md:
- Around line 22-24: Several fenced code blocks (e.g., the blocks containing
`!`git switch main`` and `!`git pull origin main --ff-only`` and other blocks
noted at ranges 34-36, 42-44, 72-76, 82-89, 93-103, 141-143, 155-160, 175-177)
are missing language specifiers; update each triple-backtick fence to include an
appropriate language hint like ```bash for shell commands or ```text/markdown
for plain text so linters and renderers can parse them correctly, ensuring each
fence that contains shell commands (`git ...`, `az ...`, etc.) uses ```bash and
other examples use a suitable specifier.
In @.claude/skills/pr-review-gate/SKILL.md:
- Around line 20-22: The fenced code blocks in
.claude/skills/pr-review-gate/SKILL.md (e.g., the block containing the gh pr
view command) are missing language specifiers; update each triple-backtick fence
for those examples (including the blocks at the other noted ranges) to include
an appropriate hint such as bash, text, or yaml (for example change ``` to
```bash or ```text) so linters and readers get correct syntax highlighting and
semantics; locate the blocks by the shown example command `gh pr view
<pr-number> --json
number,title,state,mergeable,mergeStateStatus,reviewDecision,statusCheckRollup,labels,reviews`
and apply the same change to the other listed blocks.
🪄 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: 9a8d5ba7-33dc-4862-8155-f42c7d5c4654
📒 Files selected for processing (8)
.claude/skills/apply-and-verify/SKILL.md.claude/skills/archive-and-closeout/SKILL.md.claude/skills/change-id-resolve/SKILL.md.claude/skills/closed-loop-orchestrator/SKILL.md.claude/skills/gitnexus-blast-radius/SKILL.md.claude/skills/openspec-explore-twice/SKILL.md.claude/skills/pr-review-gate/SKILL.md.gitignore
| 依 [CLAUDE.md](CLAUDE.md) 驗證順序規範：type check → lint → affected unit tests → integration / E2E only when needed。 | ||
|
|
There was a problem hiding this comment.
Verification contract is incomplete: type-check and lint gates are declared but not enforced.
Line 9 states the required order includes type check and lint, but Step 3 only mandates OpenSpec validate + tests + diff check + detect-changes. This can let static/type issues pass despite the stated policy.
Proposed fix
### Step 3：四層驗證
+#### Layer 0：type check + lint（依 service）
+
+```bash
+# Python services (example)
+!`cd _worker && python -m mypy .`
+!`cd _worker && python -m ruff check .`
+
+# Frontend service (example)
+!`cd web-viewer-sample && npm run typecheck`
+!`cd web-viewer-sample && npm run lint`
+```
+
+不過 → 先修正型別/靜態檢查問題，再進入後續驗證。
+
#### Layer 1：OpenSpec strict validateAlso applies to: 49-77
🤖 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 9 - 10, The
verification contract in SKILL.md declares "type check → lint → affected unit
tests → integration / E2E" but does not enforce type-check and lint in the Step
3 gate; update the document and pipeline notes so that the Step 3 "OpenSpec
validate + tests + diff check + detect-changes" block first runs and fails on
static/type checks (e.g., add explicit commands for Python services: python -m
mypy . and python -m ruff check .; and for frontend: npm run typecheck and npm
run lint) and require those to pass before running unit/integration tests;
ensure the text references the verification order and that failing type/lint
short-circuits the rest of Step 3.
| ``` | ||
| openspec/changes/<change-id>/ # 規格 | ||
| proposal.md / design.md / tasks.md | ||
| specs/<capability>.delta.md | ||
| <bounded-service>/... # 程式碼 | ||
| <bounded-service>/tests/... # focused tests | ||
| docs/verification/<date>-<change-id>.md # verification evidence | ||
| ``` |
There was a problem hiding this comment.
Add fenced-code languages to clear MD040 warnings.
Multiple command/template blocks are unlabeled and will keep failing markdownlint checks.
Proposed fix
-```
+```text
openspec/changes/<change-id>/ # 規格
proposal.md / design.md / tasks.md
specs/<capability>.delta.md
<bounded-service>/... # 程式碼
<bounded-service>/tests/... # focused tests
docs/verification/<date>-<change-id>.md # verification evidence- +bash
!openspec validate <change-id> --strict
-```
+```bash
# _worker
!`cd _worker && python -m pytest tests/ -x`
...
- +bash
!git diff --check
-```
+```bash
!`gitnexus detect-changes --scope staged`
- +text
(): - <一句話摘要>
<可選的多行 body 說明>
-```
+```bash
!`git push -u origin codex/openspec/<change-id>`
- +bash
!gh pr create \ --base main \ --head codex/openspec/<change-id> \ --title "<type>(<bounded-service>): <change-id> - <摘要>" \ --body-file <generated PR body>
Also applies to: 53-55, 63-75, 81-83, 89-91, 101-105, 116-118, 120-126
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 37-37: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 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 37 - 44, Several
fenced code blocks in the SKILL.md doc are unlabeled (triggering markdownlint
MD040); update each unlabeled ``` block to include the appropriate language tag
(e.g., use ```text for directory/listing blocks like the
"openspec/changes/<change-id>/ ..." block and for PR body templates, and use
```bash for command lines such as `openspec validate <change-id> --strict`, `cd
_worker && python -m pytest ...`, `git diff --check`, `gitnexus detect-changes
--scope staged`, `git push -u origin codex/openspec/<change-id>`, and the `gh pr
create \` block) so every fenced block is explicitly typed and markdownlint
MD040 is resolved.
| --- | ||
| name: change-id-resolve | ||
| description: 解析下一個正式 change-id，套用 NoSuccessorWhilePredecessorOpen gate。當使用者要開始新 OpenSpec change、詢問「下一個 change 是什麼」、或要判定 active change 起點時使用。 | ||
| allowed-tools: Bash(git status*) Bash(git fetch*) Bash(git rev-parse*) Bash(gh pr list*) Bash(gh pr view*) Read Grep Glob |
There was a problem hiding this comment.
allowed-tools does not permit a command used later (ls).
Step 4 runs ls, but Line 4 does not allow Bash(ls*). This can block execution of the skill at runtime.
Suggested fix
-allowed-tools: Bash(git status*) Bash(git fetch*) Bash(git rev-parse*) Bash(gh pr list*) Bash(gh pr view*) Read Grep Glob
+allowed-tools: Bash(git status*) Bash(git fetch*) Bash(git rev-parse*) Bash(gh pr list*) Bash(gh pr view*) Bash(ls*) Read Grep GlobAlso applies to: 45-45
🤖 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/change-id-resolve/SKILL.md at line 4, The allowed-tools list
on the SKILL.md header currently lacks permission for the ls command used later
(see Step 4); update the allowed-tools entry (the line beginning with
"allowed-tools:") to include Bash(ls*) so that Bash can execute ls at runtime
and unblock the skill; ensure the same addition is applied where the header
repeats (noted at lines referenced in the review).
|
|
||
| # Change ID Resolve | ||
|
|
||
| 依 [AGENTS.md](AGENTS.md) 規範，找出下一個正式 active change-id。 |
There was a problem hiding this comment.
Several Markdown links are likely broken due to incorrect relative paths.
This file is under .claude/skills/change-id-resolve/, so AGENTS.md, CLAUDE.md, and docs/... links should be rooted relatively (../../../...) or converted to absolute repo links.
Suggested fix
-依 [AGENTS.md](AGENTS.md) 規範，找出下一個正式 active change-id。
+依 [AGENTS.md](../../../AGENTS.md) 規範，找出下一個正式 active change-id。
...
-讀 [docs/plans/AI-BIM-governance-saas-roadmap-2026-05.md](docs/plans/AI-BIM-governance-saas-roadmap-2026-05.md)。
+讀 [docs/plans/AI-BIM-governance-saas-roadmap-2026-05.md](../../../docs/plans/AI-BIM-governance-saas-roadmap-2026-05.md)。
...
-- [AGENTS.md](AGENTS.md)：repo 邊界與 source-of-truth 順序
-- [CLAUDE.md](CLAUDE.md) §0.1：Claude 與 OpenSpec 對齊規則
-- [docs/plans/AI-BIM-governance-saas-roadmap-2026-05.md](docs/plans/AI-BIM-governance-saas-roadmap-2026-05.md)：正式 active change 來源
+- [AGENTS.md](../../../AGENTS.md)：repo 邊界與 source-of-truth 順序
+- [CLAUDE.md](../../../CLAUDE.md) §0.1：Claude 與 OpenSpec 對齊規則
+- [docs/plans/AI-BIM-governance-saas-roadmap-2026-05.md](../../../docs/plans/AI-BIM-governance-saas-roadmap-2026-05.md)：正式 active change 來源Also applies to: 36-36, 101-103
🤖 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/change-id-resolve/SKILL.md at line 9, Links to AGENTS.md,
CLAUDE.md and docs/... in SKILL.md are using incorrect relative paths and likely
broken; update each Markdown link (e.g., "AGENTS.md", "CLAUDE.md", any
"docs/..." links) to use the correct repo-relative path from the current
document (for example prefix with ../../../ to reach the repository root) or
replace them with absolute repository URLs, and verify all occurrences in the
file are fixed (including other instances of AGENTS.md, CLAUDE.md, and
docs/...).
| ``` | ||
| !`git status --porcelain` | ||
| ``` |
There was a problem hiding this comment.
Add fenced code block languages to satisfy markdownlint MD040.
Static analysis flags these fences; adding bash keeps docs lint-clean and avoids avoidable pipeline noise.
Also applies to: 29-32, 44-46, 56-58, 68-70
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 21-21: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 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/change-id-resolve/SKILL.md around lines 21 - 23, The markdown
fences in SKILL.md are missing language identifiers which triggers markdownlint
MD040; update each fenced code block (the backtick blocks shown around `git
status --porcelain` and the other occurrences at the ranges called out) to
include a language tag (use bash) so they read as fenced blocks like ```bash;
ensure you apply this change to all listed occurrences (lines referenced in the
comment: the block at the example plus the ones at 29-32, 44-46, 56-58, 68-70)
so the linter stops flagging MD040.
| ``` | ||
| /change-id-resolve | ||
| ``` |
There was a problem hiding this comment.
Add language identifiers to fenced code blocks (MD040).
These blocks currently fail markdownlint. Tag them as text (skill invocations) and bash (shell commands) to keep docs lint-clean.
Suggested edit
-```
+```text
/change-id-resolve- +text
/openspec-explore-twice
-```
+```text
/gitnexus-blast-radius pre-change <symbol1,symbol2,...>
- +text
/apply-and-verify
-```
+```text
/pr-review-gate <pr-number>
- +text
/archive-and-closeout
-```
+```bash
!`git status --short --branch`
!`git rev-parse origin/main`
!`gh pr list --state open --limit 5 --json number,title,headRefName,state`
</details>
Also applies to: 40-42, 54-56, 66-68, 83-85, 97-99, 123-127
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.22.1)</summary>
[warning] 25-25: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
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/closed-loop-orchestrator/SKILL.md around lines 25 - 27, Add
language identifiers to the fenced code blocks in
.claude/skills/closed-loop-orchestrator/SKILL.md to satisfy markdownlint MD040:
tag plain skill invocation blocks with "text" (e.g. the blocks containing
"/change-id-resolve", "/openspec-explore-twice ",
"/gitnexus-blast-radius pre-change <symbol1,symbol2,...>", "/apply-and-verify
", "/pr-review-gate ", "/archive-and-closeout
") and tag the shell command block containing backticked git/gh
commands with "bash"; update each triple-backtick opening fence accordingly for
the occurrences around lines referenced (also at 40-42, 54-56, 66-68, 83-85,
97-99, 123-127).
</details>
<!-- fingerprinting:phantom:triton:hawk -->
<!-- d98c2f50 -->
<!-- This is an auto-generated comment by CodeRabbit -->
| ``` | ||
| !`gitnexus analyze --embeddings --skills --skip-agents-md` | ||
| ``` |
There was a problem hiding this comment.
Label fenced command blocks with bash to satisfy markdownlint.
These unlabeled fences will keep triggering MD040 and add avoidable CI/doc noise.
Proposed fix
-```
+```bash
!`gitnexus analyze --embeddings --skills --skip-agents-md`- +bash
!gitnexus impact --target <symbol> --direction upstream
-```
+```bash
!`gitnexus detect-changes --scope staged`
- +bash
!gitnexus analyze --embeddings --skills --skip-agents-md
!gitnexus detect-changes --scope staged
-```
+```bash
!`git diff --name-only --cached`
</details>
Also applies to: 31-33, 69-71, 94-97, 101-103
<details>
<summary>🧰 Tools</summary>
<details>
<summary>🪛 markdownlint-cli2 (0.22.1)</summary>
[warning] 21-21: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
</details>
</details>
<details>
<summary>🤖 Prompt for AI Agents</summary>
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/gitnexus-blast-radius/SKILL.md around lines 21 - 23, The
markdown contains unlabeled fenced code blocks with shell commands (e.g., the
backticked lines containing gitnexus analyze --embeddings --skills
--skip-agents-md, gitnexus impact --target --direction upstream,
gitnexus detect-changes --scope staged, and git diff --name-only --cached) which
triggers MD040; update each fenced code block around these commands to include
the language label "bash" (i.e., replace withbash) at every occurrence
noted (including the other locations mentioned) so the code fences are properly
labeled for markdownlint.
</details>
<!-- fingerprinting:phantom:triton:hawk -->
<!-- 4e71b3a2 -->
<!-- This is an auto-generated comment by CodeRabbit -->
| ``` | ||
| openspec/changes/<change-id>/ | ||
| ├── proposal.md | ||
| ├── design.md | ||
| ├── tasks.md | ||
| └── specs/ | ||
| └── <capability>.delta.md | ||
| ``` |
There was a problem hiding this comment.
Add fenced-code languages for command/tree blocks.
Line 20 and Line 68 use unlabeled fenced blocks, which will keep failing MD040 and reduce readability in rendered docs.
Proposed fix
-```
+```text
openspec/changes/<change-id>/
├── proposal.md
├── design.md
├── tasks.md
└── specs/
└── <capability>.delta.md- +bash
!openspec validate <change-id> --strict
Also applies to: 68-70
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 20-20: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 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/openspec-explore-twice/SKILL.md around lines 20 - 27, The
unlabeled fenced code blocks showing the directory tree (the block containing
"openspec/changes/<change-id>/ ├── proposal.md ...") and the command block
containing the command invocation starting with "!`openspec validate <change-id>
--strict`" need explicit languages to satisfy MD040 and improve readability;
change the tree block fence from ``` to ```text and change the command block
fence from ``` to ```bash so the tree uses a plain-text fence and the command
uses a bash shell fence respectively.
| ### Step 2：等待 CI checks | ||
|
|
||
| ``` | ||
| !`gh pr checks <pr-number>` | ||
| ``` | ||
|
|
||
| 統計： | ||
| - `pass` 數 | ||
| - `fail` 數 | ||
| - `pending` 數 | ||
|
|
||
| 若 `fail > 0` → 進入 Debug Loop（Step 4） | ||
| 若 `pending > 0` → 等待，建議使用者過幾分鐘再執行；不自己 sleep。 | ||
|
|
||
| ### Step 3：列出 review comments | ||
|
|
||
| ``` | ||
| !`gh pr view <pr-number> --json reviews,comments` | ||
| !`gh api repos/{owner}/{repo}/pulls/<pr-number>/comments` | ||
| ``` | ||
|
|
||
| 分類： | ||
| - `APPROVED` | ||
| - `REQUEST_CHANGES`（blocking） | ||
| - `COMMENTED`（non-blocking） | ||
|
|
||
| ### Step 4：Debug Loop（有 blocking risk 時） | ||
|
|
||
| 針對每個 `REQUEST_CHANGES` comment： | ||
|
|
||
| 1. 把 comment 文字摘要成 debug target（symbol / file / function） | ||
| 2. 呼叫 `gitnexus-blast-radius post-change` skill： | ||
|
|
||
| ``` | ||
| /gitnexus-blast-radius post-change | ||
| ``` | ||
|
|
||
| 3. 依結果回到 `apply-and-verify` skill 修正、重 push、回 Step 2 |
There was a problem hiding this comment.
Fix logic inconsistency between CI failure and review comment handling.
There's a logic mismatch in the Debug Loop flow:
- Line 39 (Step 2): States that if
fail > 0(CI check failures) → go to Debug Loop (Step 4) - Lines 54-65 (Step 4): Describes Debug Loop as handling
REQUEST_CHANGEScomments specifically
These are fundamentally different scenarios:
- CI failures require fixing code/tests and re-running the pipeline
- REQUEST_CHANGES comments require analyzing reviewer feedback and targeted debugging with GitNexus
The workflow should distinguish between these cases:
- CI failures should trigger a different remediation path (e.g., "CI Failure Resolution Loop")
- Debug Loop (Step 4) should remain focused on reviewer-requested changes
🔧 Proposed fix to separate CI failure and review comment handling
### Step 2：等待 CI checks
!gh pr checks <pr-number>
統計：
- `pass` 數
- `fail` 數
- `pending` 數
-若 `fail > 0` → 進入 Debug Loop（Step 4）
+若 `fail > 0` → CI 失敗，需修正程式碼/測試並重新 push；回到 Step 2 重新檢查
若 `pending > 0` → 等待，建議使用者過幾分鐘再執行；不自己 sleep。
+
+**注意**：CI 失敗與 reviewer REQUEST_CHANGES 是不同情境，CI 失敗時不進入 Debug Loop（Step 4）。
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 30-30: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 44-44: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
[warning] 61-61: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 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/pr-review-gate/SKILL.md around lines 28 - 65, Update the
workflow text to separate CI failures from reviewer-requested changes: change
the Step 2 rule for "fail > 0" to route to a new "CI Failure Resolution Loop"
(describe: fix code/tests, re-run CI, then return to Step 2) and add a
clarifying note that CI failures do not enter the "Debug Loop (Step 4)"; leave
Step 4 ("Debug Loop") explicitly scoped to handling `REQUEST_CHANGES` comments
(summarize comment → call `/gitnexus-blast-radius post-change` →
apply-and-verify → re-push → back to Step 2) so readers can clearly distinguish
the two remediation paths.
There was a problem hiding this comment.
Pull request overview
This PR introduces a set of 7 Claude Code “skills” documents to codify a 14-step closed-loop workflow (AI-BIM-governance → OpenSpec → GitNexus → PR review → archive/closeout), and updates .gitignore so these specific skill artifacts under .claude/skills/ are tracked while other .claude/ content remains ignored.
Changes:
- Updated
.gitignoreto unignore and track 7 specific.claude/skills/<skill>/directories. - Added 7 new
SKILL.mdworkflow artifacts covering change-id resolution, double-explore, GitNexus blast radius checks, apply+verify, PR review gating, and archive+closeout. - Added an orchestrator skill that composes the above into a single end-to-end flow with manual confirmation gates.
Reviewed changes
Copilot reviewed 7 out of 8 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
.gitignore |
Unignores .claude/skills/ and selectively tracks 7 skill directories. |
.claude/skills/closed-loop-orchestrator/SKILL.md |
Defines the end-to-end 14-step orchestration across the other skills. |
.claude/skills/change-id-resolve/SKILL.md |
Specifies how to resolve the next active change-id and apply predecessor gating. |
.claude/skills/openspec-explore-twice/SKILL.md |
Enforces two OpenSpec explore rounds with “no open questions” gates. |
.claude/skills/gitnexus-blast-radius/SKILL.md |
Wraps GitNexus pre-change impact + post-change scope drift checks (with fallback). |
.claude/skills/apply-and-verify/SKILL.md |
Describes apply phase steps plus a 4-layer verification and PR creation workflow. |
.claude/skills/pr-review-gate/SKILL.md |
Defines CI/review gates and a manual merge confirmation step. |
.claude/skills/archive-and-closeout/SKILL.md |
Defines archive PR flow, roadmap/spec sync expectations, and branch closeout. |
Comments suppressed due to low confidence (4)
.claude/skills/closed-loop-orchestrator/SKILL.md:92
- 這裡說
pr-review-gate會在同意後執行gh pr merge --squash --auto --delete-branch，但pr-review-gate自己的 Step 6 明確寫「不用 --auto（除非使用者特別說）」。兩份 skill 規範互相矛盾會導致實際 gate 行為不一致；建議統一：預設不使用--auto，並在 orchestrator 描述中移除--auto或改成「視使用者指示」。
該 skill 會：
- 跑 `gh pr checks` 等待 CI 結果
- 列出 review comments
- 若有 blocking risk，自動觸發 `gitnexus-blast-radius post-change` 進入 debug loop
- 全綠後**等待使用者明確同意**才 `gh pr merge --squash --auto --delete-branch`
.claude/skills/pr-review-gate/SKILL.md:11
- 此檔中的
[CLAUDE.md](CLAUDE.md)等連結以目前相對路徑在 GitHub 會指向.claude/skills/pr-review-gate/CLAUDE.md而失效。建議改成 root-relative（例如/CLAUDE.md）或正確的相對路徑（例如../../../CLAUDE.md）。
# PR Review Gate
依 [CLAUDE.md](CLAUDE.md) 與 PDF 規範，merge 是不可逆動作，必須使用者明確同意。
.claude/skills/change-id-resolve/SKILL.md:10
- 此檔的
[AGENTS.md](AGENTS.md)/[CLAUDE.md](CLAUDE.md)/[docs/plans/...](docs/plans/...)連結目前會解析成.claude/skills/change-id-resolve/...底下的路徑而失效。建議改成 root-relative（例如/AGENTS.md、/docs/plans/...）或補上正確相對路徑。
# Change ID Resolve
依 [AGENTS.md](AGENTS.md) 規範，找出下一個正式 active change-id。
.claude/skills/archive-and-closeout/SKILL.md:11
- 此檔的
[AGENTS.md](AGENTS.md)、[docs/plans/...](docs/plans/...)連結會因為相對路徑而失效（會指向.claude/skills/archive-and-closeout/...）。建議改成 root-relative（例如/AGENTS.md、/docs/plans/...）或使用正確相對路徑。
# Archive and Closeout
依 [AGENTS.md](AGENTS.md) closeout flow：implementation PR merge 後另開 archive branch，不得偷塞進 implementation PR。
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| # Closed-Loop Orchestrator | ||
|
|
||
| 依 [docs/plans/AI-BIM-governance-saas-roadmap-2026-05.md](docs/plans/AI-BIM-governance-saas-roadmap-2026-05.md) 與 [AGENTS.md](AGENTS.md) 規範，串接完整的 OpenSpec change 閉環。 |
| name: pr-review-gate | ||
| description: implementation PR 開出後的 review gate；等待 CI checks、列出 reviewer comments、若有 blocking risk 自動觸發 GitNexus debug loop、全綠後等使用者明確同意才 merge。Merge 動作絕不自動執行，必須使用者人工同意。 | ||
| disable-model-invocation: true | ||
| allowed-tools: Bash(gh pr*) Bash(git*) Skill Read Grep |
| --- | ||
| name: change-id-resolve | ||
| description: 解析下一個正式 change-id，套用 NoSuccessorWhilePredecessorOpen gate。當使用者要開始新 OpenSpec change、詢問「下一個 change 是什麼」、或要判定 active change 起點時使用。 | ||
| allowed-tools: Bash(git status*) Bash(git fetch*) Bash(git rev-parse*) Bash(gh pr list*) Bash(gh pr view*) Read Grep Glob |
|
|
||
| # GitNexus Blast Radius | ||
|
|
||
| 依 [CLAUDE.md](CLAUDE.md) GitNexus Always Do 規範，本 skill 把 GitNexus 包成兩個明確 phase：改前的 blast radius、改後的 scope 驗證。 |
| name: archive-and-closeout | ||
| description: implementation PR merge 後執行 archive 與 closeout：建 archive branch、跑 openspec archive、同步 specs 與 roadmap markdown/HTML、開 archive PR、等使用者同意後 merge、最後做 branch cleanup。所有 merge 動作絕不自動執行。 | ||
| disable-model-invocation: true | ||
| allowed-tools: Bash(git*) Bash(gh pr*) Bash(openspec archive*) Read Edit Write Grep |
|
|
||
| # OpenSpec Explore Twice | ||
|
|
||
| 依 [CLAUDE.md](CLAUDE.md) §0.1 規範，OpenSpec change 必須至少做兩輪 explore，open questions 不可遺留。 |
| # Apply and Verify | ||
|
|
||
| 依 [CLAUDE.md](CLAUDE.md) 驗證順序規範：type check → lint → affected unit tests → integration / E2E only when needed。 | ||
|
|
依 PR #36 code review 建議 1 與 4： 1. 收斂 `Bash(git*)` 全 wildcard 為命名 glob，避免誤觸 git reset --hard / branch -D： - apply-and-verify：拆成 git add/commit/push/diff/status/log - pr-review-gate：拆成 git push/status/log（read-only + push only） - archive-and-closeout：拆成 git switch/pull/status/fetch/branch/add/commit/push/diff 並補上 openspec validate / gitnexus detect-changes 2. gitnexus-blast-radius fallback 補強： - 加上「連續 3 次失敗就升 issue 並暫停」的停損條件 - 避免 git-diff-only fallback 變成永久 technical debt
![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: b05697b5bb
ℹ️ 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".
| # bim-review-coordinator | ||
| !`cd bim-review-coordinator && python -m pytest tests/ -x` | ||
|
|
||
| # web-viewer-sample | ||
| !`cd web-viewer-sample && npm test` |
There was a problem hiding this comment.
For changes touching the Node services, these focused-test commands send agents down failing paths: bim-review-coordinator is a Vitest/TypeScript package with npm test in package.json, not a Python pytest service, and web-viewer-sample has no test script at all. Any apply run scoped to either service will fail before commit even when the code is valid; use the existing service scripts such as coordinator npm test and viewer npm run build/npm run verify instead.
Useful? React with 👍 / 👎.
| !`openspec validate --strict` | ||
| !`git diff --check` | ||
| !`gitnexus detect-changes --scope staged` |
There was a problem hiding this comment.
When this skill reaches archive verification, the frontmatter only whitelists Bash(openspec archive*), but this step invokes openspec validate --strict; similarly the GitNexus command is only safe if the Bash(git*) glob is intentionally meant to cover gitnexus. In Claude skill execution this makes the mandatory validation step unavailable, so archive PRs can get blocked or skip the checks the workflow requires.
Useful? React with 👍 / 👎.
| !`gh pr view <pr-number> --json reviews,comments` | ||
| !`gh api repos/{owner}/{repo}/pulls/<pr-number>/comments` |
There was a problem hiding this comment.
This review-gate step asks the skill to run gh api .../pulls/<pr>/comments, but the skill only grants Bash(gh pr*), so the command that fetches inline review comments is not allowed. In PRs with blocking line comments, the gate will miss the data needed for the debug loop or require an unexpected permission escalation; add the gh api command to the allowed tools or use an allowed gh pr command that returns the same comments.
Useful? React with 👍 / 👎.
| 讀 `openspec/changes/<change-id>/tasks.md`，比對： | ||
| - `tasks.md` 預期碰到的 symbols / files | ||
| - `detect-changes` 實際碰到的 symbols / files |
There was a problem hiding this comment.
In post-change mode this step requires reading openspec/changes/<change-id>/tasks.md, but the skill frontmatter only allows Bash commands and does not grant Read/Grep/Glob. That means the mandatory comparison of actual GitNexus scope against the expected task scope cannot be performed, so scope drift may either block the workflow unexpectedly or be skipped.
Useful? React with 👍 / 👎.
| ### Step 3：讀 main 上的 roadmap | ||
|
|
||
| 讀 [docs/plans/AI-BIM-governance-saas-roadmap-2026-05.md](docs/plans/AI-BIM-governance-saas-roadmap-2026-05.md)。 |
There was a problem hiding this comment.
When this resolver is invoked from an existing feature/archive branch, this instruction reads the worktree's roadmap after only fetching origin/main, so it can select a change id from unmerged branch edits even though the rule above says only main counts. Use git show origin/main:docs/plans/... or switch to a clean main before reading, otherwise successor gating can be based on the wrong roadmap.
Useful? React with 👍 / 👎.
| #### Layer 4：GitNexus scope drift 驗證 | ||
|
|
||
| ``` | ||
| !`gitnexus detect-changes --scope staged` | ||
| ``` | ||
|
|
||
| 呼叫 `gitnexus-blast-radius post-change` skill，比對 `affected_symbols` 是否 ⊆ tasks.md 預期 scope。 |
There was a problem hiding this comment.
This verification layer tells the agent to call gitnexus-blast-radius post-change, but the skill frontmatter does not include the Skill tool. When the apply flow reaches this required scope-drift comparison, the nested skill invocation is unavailable, so the workflow either blocks after detect-changes or skips the expected-vs-actual scope check.
Useful? React with 👍 / 👎.
| ### Step 9：等待 archive PR review | ||
|
|
||
| 呼叫 `pr-review-gate`： | ||
|
|
||
| ``` | ||
| /pr-review-gate <archive-pr-number> | ||
| ``` |
There was a problem hiding this comment.
Archive closeout requires handing the archive PR to /pr-review-gate, but this skill's allowed tools do not include Skill. In the archive flow, that makes the mandatory review/merge gate impossible to invoke from the skill, leaving the PR at Step 9 without the promised CI and review checks.
Useful? React with 👍 / 👎.
| ``` | ||
| !`git switch main` | ||
| !`git fetch origin --prune` | ||
| !`git status --short --branch` | ||
| !`git branch --no-merged origin/main` | ||
| ``` |
There was a problem hiding this comment.
This closeout inventory omits the AGENTS-required git branch -vv --no-abbrev, remote git branch -r --no-merged origin/main, and PR-state checks before deleting merged/superseded branches. In squash-merge or superseded-branch cases, relying only on local --no-merged can misclassify branches and skip remote cleanup evidence, so the skill should perform the full read-only inventory before any deletion.
Useful? React with 👍 / 👎.
| - 跑 `gh pr checks` 等待 CI 結果 | ||
| - 列出 review comments | ||
| - 若有 blocking risk，自動觸發 `gitnexus-blast-radius post-change` 進入 debug loop | ||
| - 全綠後**等待使用者明確同意**才 `gh pr merge --squash --auto --delete-branch` |
There was a problem hiding this comment.
This orchestrator summary tells users the review gate will run gh pr merge --squash --auto --delete-branch, but the actual gate below explicitly avoids --auto, and the official gh pr merge manual defines --auto as merging automatically once requirements are met (https://cli.github.com/manual/gh_pr_merge). In contexts where checks are still pending or merge queues are involved, this contradicts the repository's manual merge-confirmation policy and can schedule a future merge rather than performing only the just-approved action.
Useful? React with 👍 / 👎.
| ``` | ||
| # _worker | ||
| !`cd _worker && python -m pytest tests/ -x` | ||
|
|
||
| # _bim-control | ||
| !`cd _bim-control && python -m pytest tests/ -x` |
There was a problem hiding this comment.
The Python service test examples are executed as cd ... && python -m pytest, but the skill only allows Bash(pytest*)/Bash(npm*) rather than commands starting with cd or python. For _worker or _bim-control changes, the documented focused-test commands are therefore not allowed by the skill sandbox even though they are the required service-local invocation.
Useful? React with 👍 / 👎.
Follow-up fix（b1550bc）依本 PR code review 建議 1 與 4 已 push 第二次 commit： 建議 1：收斂
|
| Skill | 修改前 | 修改後 |
|---|---|---|
apply-and-verify |
Bash(git*) |
Bash(git add*) Bash(git commit*) Bash(git push*) Bash(git diff*) Bash(git status*) Bash(git log*) |
pr-review-gate |
Bash(git*) |
Bash(git push*) Bash(git status*) Bash(git log*) + Bash(gh api*) |
archive-and-closeout |
Bash(git*) |
Bash(git switch*) Bash(git pull*) Bash(git status*) Bash(git fetch*) Bash(git branch*) Bash(git add*) Bash(git commit*) Bash(git push*) Bash(git diff*)、補上 Bash(openspec validate*) Bash(gitnexus detect-changes*) |
效果：移除 git reset --hard、git push -f、git branch -D 等破壞性指令的「免確認權限」。
建議 4：gitnexus-blast-radius fallback 停損
加上明確的失敗計數表：
- 第 1 次 → analyze 後重試
- 第 2 次 → 用
git diff --name-onlyfallback，PR body 標⚠️ - 第 3 次 → 停止 +
gh issue create升 issue + 暫停 commit/merge 流程
防止 fallback 變成永久 technical debt（PR #35 曾出現的真實風險）。
Diff scope
.claude/skills/apply-and-verify/SKILL.md | 2 +-
.claude/skills/archive-and-closeout/SKILL.md | 2 +-
.claude/skills/gitnexus-blast-radius/SKILL.md | 12 +++++++++++-
.claude/skills/pr-review-gate/SKILL.md | 2 +-
4 files changed, 14 insertions(+), 4 deletions(-)
建議 2（trigger phrases 中英文同義詞）與建議 3（skill 間 contract schema）保留為下次迭代採納，因為這兩條需要實際跑一輪 closed-loop 收集 mismatch / interface 使用案例後再優化，現在做容易過度設計。
PR 維持 OPEN 狀態，等待 @monkey1sai 同意 merge。
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 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:
- Around line 87-91: Layer 4's scope drift check uses "gitnexus detect-changes
--scope staged" but the workflow never stages files (Layer 3 only runs "git diff
--check"), so the staged set can be empty and the check will falsely pass; add
an explicit staging step before Layer 4 (for example call "git add -p" or
per-file "git add <file>") so that changed files are actually in the staged
index before running "gitnexus detect-changes --scope staged", ensuring the
scope drift verification in Layer 4 detects real changes.
In @.claude/skills/archive-and-closeout/SKILL.md:
- Around line 70-76: Add an explicit staging step before running the staged-only
verification: insert a command to stage the modified directories (e.g. run git
add openspec/ docs/plans/) before the series of checks that include openspec
validate, git diff --check and gitnexus detect-changes --scope staged so that
gitnexus actually inspects the intended changes; update the block around the
Step 6 commands (the triple-backtick snippet containing openspec validate, git
diff --check, gitnexus detect-changes) to include this git add command
immediately before gitnexus detect-changes.
🪄 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: 3b1861a1-bf95-4101-b84a-e8b034d845f1
📒 Files selected for processing (4)
.claude/skills/apply-and-verify/SKILL.md.claude/skills/archive-and-closeout/SKILL.md.claude/skills/gitnexus-blast-radius/SKILL.md.claude/skills/pr-review-gate/SKILL.md
| #### Layer 4：GitNexus scope drift 驗證 | ||
|
|
||
| ``` | ||
| !`gitnexus detect-changes --scope staged` | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
cat -n .claude/skills/apply-and-verify/SKILL.md | sed -n '75,105p'Repository: monkey1sai/AI-BIM-governance
Length of output: 838
🏁 Script executed:
wc -l .claude/skills/apply-and-verify/SKILL.mdRepository: monkey1sai/AI-BIM-governance
Length of output: 117
🏁 Script executed:
cat -n .claude/skills/apply-and-verify/SKILL.md | head -90Repository: monkey1sai/AI-BIM-governance
Length of output: 3122
🏁 Script executed:
cat -n .claude/skills/apply-and-verify/SKILL.md | sed -n '87,120p'Repository: monkey1sai/AI-BIM-governance
Length of output: 869
🏁 Script executed:
fd gitnexusRepository: monkey1sai/AI-BIM-governance
Length of output: 100
🏁 Script executed:
grep -r "git add" .claude/skills/apply-and-verify/ || echo "No git add found in file"Repository: monkey1sai/AI-BIM-governance
Length of output: 413
🏁 Script executed:
cat -n CLAUDE.md | grep -A5 -B5 "stage\|git add" || echo "No staging references found"Repository: monkey1sai/AI-BIM-governance
Length of output: 4056
🏁 Script executed:
grep -n "不跑.*git add" .claude/skills/apply-and-verify/SKILL.mdRepository: monkey1sai/AI-BIM-governance
Length of output: 104
🏁 Script executed:
cat -n docs/gitnexus-validation.mdRepository: monkey1sai/AI-BIM-governance
Length of output: 5224
🏁 Script executed:
cat -n .claude/skills/apply-and-verify/SKILL.md | sed -n '175,189p'Repository: monkey1sai/AI-BIM-governance
Length of output: 521
Layer 4 runs scope drift check against potentially empty staged set.
Layer 4 uses --scope staged to detect scope drift, but the workflow has no explicit staging instruction before it. Layer 3 checks unstaged changes with git diff --check, yet no git add command follows. If files remain unstaged when Layer 4 executes, the staged set is empty and scope verification silently passes without detecting actual changes, defeating the safety check's purpose.
Add a staging step before Layer 4 (e.g., git add -p or explicit per-file staging per the safety guidelines) to ensure changed files are staged before running scope drift verification.
🧰 Tools
🪛 LanguageTool
[grammar] ~87-~87: Ensure spelling is correct
Context: ...whitespace / formatting 問題。 #### Layer 4：GitNexus scope drift 驗證 ``` !`gitnexus detect-c...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🪛 markdownlint-cli2 (0.22.1)
[warning] 89-89: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 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 87 - 91, Layer 4's
scope drift check uses "gitnexus detect-changes --scope staged" but the workflow
never stages files (Layer 3 only runs "git diff --check"), so the staged set can
be empty and the check will falsely pass; add an explicit staging step before
Layer 4 (for example call "git add -p" or per-file "git add <file>") so that
changed files are actually in the staged index before running "gitnexus
detect-changes --scope staged", ensuring the scope drift verification in Layer 4
detects real changes.
| ### Step 6：四層驗證 | ||
|
|
||
| ``` | ||
| !`openspec validate --strict` | ||
| !`git diff --check` | ||
| !`gitnexus detect-changes --scope staged` | ||
| ``` |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
cat -n ".claude/skills/archive-and-closeout/SKILL.md" | head -100Repository: monkey1sai/AI-BIM-governance
Length of output: 3486
🏁 Script executed:
sed -n '80,120p' ".claude/skills/archive-and-closeout/SKILL.md" | cat -nRepository: monkey1sai/AI-BIM-governance
Length of output: 1312
🏁 Script executed:
sed -n '100,150p' ".claude/skills/archive-and-closeout/SKILL.md" | cat -nRepository: monkey1sai/AI-BIM-governance
Length of output: 1636
Add explicit staging before Step 6 verification.
At Line 75, gitnexus detect-changes --scope staged runs without files being staged first, so the verification would find no changes despite modifications in Steps 3–5. Add an explicit staging step before the detect-changes command to verify the correct directories (openspec/ and docs/plans/).
Proposed fix
### Step 6：四層驗證
+!git add openspec/ docs/plans/
!openspec validate --strict
!git diff --check
!gitnexus detect-changes --scope staged
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 72-72: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 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/archive-and-closeout/SKILL.md around lines 70 - 76, Add an
explicit staging step before running the staged-only verification: insert a
command to stage the modified directories (e.g. run git add openspec/
docs/plans/) before the series of checks that include openspec validate, git
diff --check and gitnexus detect-changes --scope staged so that gitnexus
actually inspects the intended changes; update the block around the Step 6
commands (the triple-backtick snippet containing openspec validate, git diff
--check, gitnexus detect-changes) to include this git add command immediately
before gitnexus detect-changes.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b1550bc8f4
ℹ️ 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".
| |---|---| | ||
| | 第 1 次失敗 | 跑 `gitnexus analyze --embeddings --skills --skip-agents-md` 後重試 | | ||
| | 第 2 次失敗 | 改用 `git diff --name-only --cached` 作 fallback，但在 PR body 標記 ⚠️ | | ||
| | **第 3 次失敗（同一 session）** | **停止**：升為 issue（`gh issue create`），標題格式 `gitnexus: detect-changes repeatedly failing on <branch>`，body 附最近 3 次失敗指令與 stderr，並暫停該 change 的 commit / merge 流程，等修復或 reviewer 明確 sign-off「accept git-diff-only fallback for this PR」後再繼續 | |
There was a problem hiding this comment.
When detect-changes fails three times in this post-change path, the skill makes gh issue create the required escalation, but this skill's allowed-tools only permits GitNexus, git diff, and git status Bash commands. In that failure scenario the mandatory stop-loss action is unavailable, so the workflow either blocks or skips the issue evidence it says is required; add an allowed Bash(gh issue*)/Bash(gh*) entry or make this an explicit manual step.
Useful? React with 👍 / 👎.
| #### Layer 4：GitNexus scope drift 驗證 | ||
|
|
||
| ``` | ||
| !`gitnexus detect-changes --scope staged` |
There was a problem hiding this comment.
In a normal apply run this verification step happens before the Commit step and there is no prior instruction to git add the worktree, so --scope staged can inspect an empty index and report no affected symbols even when the implementation changed files. That lets the scope-drift gate pass without checking the real diff; either stage the intended files before this layer or use a working-tree/all-changes scope here.
Useful? React with 👍 / 👎.
| **Gate**： | ||
| - `blockers` 非空 → STOP 並回報 | ||
| - 若 `branch_plan == "new"` → `git switch -c codex/openspec/<change-id>` | ||
| - 若 `branch_plan == "continue-existing"` → `git switch <branch>` 並 pull rebase |
There was a problem hiding this comment.
When branch_plan == "continue-existing", this path explicitly requires a pull/rebase after switching to the existing branch, but the skill's allowed-tools only grants git status, fetch, switch, and rev-parse for Git commands. Any run that resumes an already-open change cannot perform the documented sync step, leaving the agent either blocked or continuing from a stale local branch.
Useful? React with 👍 / 👎.
| ### Step 2：等待 CI checks | ||
|
|
||
| ``` | ||
| !`gh pr checks <pr-number>` |
There was a problem hiding this comment.
For PRs with pending checks, this command can terminate the skill before the documented pending > 0 branch runs: the official gh pr checks manual says pending checks use additional exit code 8, and it also exposes a bucket field only with --json for pass/fail/pending classification. Use gh pr checks --json ... and explicitly handle exit 8, otherwise normal in-progress CI can look like a command failure instead of a wait condition.
Useful? React with 👍 / 👎.
| ### Step 3：列出 review comments | ||
|
|
||
| ``` | ||
| !`gh pr view <pr-number> --json reviews,comments` |
There was a problem hiding this comment.
On PRs where a reviewer requested changes and later approved, reviews still contains the old REQUEST_CHANGES entry, so the Step 4 classification can treat an already-resolved review as blocking. The gh pr view JSON fields include latestReviews and this skill already fetches reviewDecision in Step 1, so base the blocking gate on the latest/effective review state rather than the full historical reviews list.
Useful? React with 👍 / 👎.
| 讀同名 `.html`（若存在），同步更新 archive 段落、Phase 狀態。 | ||
| 若無 `.html` → 跳過，但在 archive PR body 註明。 |
There was a problem hiding this comment.
If the roadmap HTML is missing, this branch tells the archive flow to skip it, but the workspace closeout rule requires archive sync to actively produce or update the same-name HTML view after the Markdown roadmap is synchronized. In that scenario an archive PR can be opened without the required derived roadmap view, so the skill should generate the HTML or stop for a documented blocker rather than silently skipping it.
Useful? React with 👍 / 👎.
harden-internal-auth-and-config-hygiene: #2 host-native token(已存在)補 test+GET comment / #6 coordinator internal middleware(已存在)comment+test / #36 退役 event 過濾 test / #26 kit-manager CORS 可設定+compose env / #23 deploy env fallback warning+missing throw。#29 evidence 移出(archive immutable,走獨立 PR)。opus 4-lens 全 LGTM + 外部 reviewer fix。
變更摘要
依「三技能閉環自動化工作流設計研究報告」PDF 結論，落地 7 個 Claude Code skills，把 AI-BIM-governance agent / OpenSpec / GitNexus 三技能排成可審查的分層閉環，覆蓋 OpenSpec change lifecycle 完整 14 步驟（起點判定 → explore → 風險判讀 → apply → review → archive → closeout）。
修改原因
PDF 報告（Anthropic conversation context）核心結論：
把上述規則寫成可重複呼叫的 Claude Code skills，是讓閉環從「文件建議」變成「機制」的最小落地。
主要變更
.gitignore：碰出 7 個 skill 目錄為 tracked，其餘.claude/維持 ignoreddisable-model-invocation: true，merge/archive 前停下等使用者同意驗證方式
風險與影響
回滾方式
若決定不採用：
後續建議
🤖 Generated with Claude Code
Summary by CodeRabbit
Documentation
Chores