docs(mega-swarm): fix 35 audit findings — dedup, accuracy, modernization#133
docs(mega-swarm): fix 35 audit findings — dedup, accuracy, modernization#133
Conversation
Executed all 3 phases in parallel via rules-agent, docs-agent, claude-md-agent. Removed: - .claude/rules/engineering-philosophy.md — complete duplicate of engineering-principles.md (~900 tokens/session wasted, P0) Changed: - thought-transparency.md: removed sequential-execution clause contradicting LAW 3, removed duplicate Silent Processing section - devops-calms.md: split Sharing section into Claude vs external-AI channels; MTTR standardized - engineering-principles.md: fixed duplicate #25 tag → #25b for composition-over-inheritance - solid-principles.md: compressed to table format; fixed metacognitive-guard SRP description - error-handling.md: replaced inapplicable retry-with-backoff with re-run-after-fix guidance - docs/ARCHITECTURE.md: fixed directory tree; added passive context layers; replaced Section 5/7 with pointers; fixed coordination channels; updated Last Verified - docs/WORKFLOWS.md: added trigger-docs.yml section; added commit-integrity-hook to pre-commit checklist - docs/QUICK-REFERENCE.md: added /hookify:help; clarified eight-gates/hades are skills; fixed hades agent count - docs/PLUGINS.md: removed fake required fields; added capability declaration fields - CLAUDE.md: replaced directory tree with pointer; added turbo-fix/fix-pipeline to routing; removed plugin structure tree; reduced CI section; added documentation paths section Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
|
Caution Review failedFailed to post review comments 📝 WalkthroughWalkthroughMultiple documentation and rule files are updated to reorganize content, move inline information to external references, add new orchestration commands (turbo-fix, fix-pipeline), simplify plugin requirements, and update various guidance principles across rules and docs. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~22 minutes 🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 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 |
Summary of ChangesHello @ANcpLua, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly refines the project's documentation and internal rules by addressing 35 audit findings related to deduplication, accuracy, and modernization. The changes aim to improve the clarity, consistency, and efficiency of information for both human and AI agents, ensuring that the guiding principles and architectural descriptions are precise and up-to-date. By removing redundant content and correcting outdated or contradictory instructions, the PR enhances the overall maintainability and usability of the project's knowledge base. Highlights
Changelog
Activity
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
The pull request effectively addresses 35 audit findings by deduplicating content, improving accuracy, and modernizing documentation. Key changes include the removal of engineering-philosophy.md, updates to thought-transparency.md to align with parallel execution principles, and various fixes across .claude/rules/ and docs/ files. The CHANGELOG.md has been comprehensively updated to reflect these changes. The modifications enhance clarity, reduce redundancy, and ensure consistency across the documentation and rule sets.
I am having trouble creating individual review comments. Click here to see my feedback.
.claude/rules/devops-calms.md (30)
The change from "Recovery Time" to "MTTR" is a good standardization, aligning with common DevOps metrics terminology.
.claude/rules/devops-calms.md (35-36)
Separating Claude coordination channels from external-AI coordination channels improves clarity and reduces potential confusion regarding communication protocols for different AI agents.
.claude/rules/solid-principles.md (9-17)
The refactoring of the Single Responsibility Principle section into a table significantly improves readability and makes it easier to grasp each plugin's core function at a glance. This is a great improvement for maintainability.
.claude/rules/solid-principles.md (30-31)
The updated Interface Segregation Principle explanation is more precise, clearly defining the minimal requirements for a plugin and highlighting optional components.
Only `plugin.json` + `README.md` are required. All other directories (`skills/`, `commands/`, `hooks/`, `agents/`) are optional.
.claude/rules/solid-principles.md (34-35)
The Dependency Inversion Principle is now explained more succinctly, emphasizing orchestration via Skills and the separation of concerns between contracts and implementations.
Plugins orchestrate via Skills. Skills define the contract. MCP servers implement. Plugins never implement low-level operations.
.claude/rules/thought-transparency.md (21-27)
Removing the "Granular Task Decomposition" section is a good change, as the description in the PR indicates it contradicted LAW 3 (parallel lanes). This improves consistency across the documentation.
.claude/rules/thought-transparency.md (37-41)
Removing the "Silent Processing with Tracked Updates" section eliminates redundant information, as the TodoWrite mechanism is already covered under "Mental State Bookkeeping."
CHANGELOG.md (9-11)
The CHANGELOG.md entry for the removal of engineering-philosophy.md is clear and provides a good rationale for the deletion, highlighting the token waste.
CHANGELOG.md (15-24)
The detailed Changed section in the CHANGELOG.md is very helpful, providing a comprehensive overview of all modifications across various files. This level of detail is excellent for tracking changes and understanding their impact.
CLAUDE.md (104-110)
Replacing the large directory tree with a pointer to docs/ARCHITECTURE.md and listing key paths here is a good way to keep CLAUDE.md concise while still providing essential navigation. This improves readability and reduces duplication.
CLAUDE.md (125-129)
Adding turbo-fix and fix-pipeline to the core routing logic is a valuable update, providing clear guidance for handling critical bugs and audit findings.
CLAUDE.md (182-184)
Including turbo-fix and fix-pipeline in the exodia commands list further clarifies their availability and purpose within the multi-agent orchestration framework.
CLAUDE.md (522-524)
Removing the detailed plugin structure and instead referencing docs/ARCHITECTURE.md is a good move for maintaining a single source of truth and keeping CLAUDE.md focused on operational aspects. The explicit mention of required fields is also helpful.
CLAUDE.md (588)
Pointing to docs/WORKFLOWS.md for CI pipeline documentation is an effective way to centralize detailed information and keep CLAUDE.md high-level.
CLAUDE.md (697-700)
Expanding the Documentation Paths section with more specific links to QUICK-REFERENCE.md, WORKFLOWS.md, PLUGINS.md, and ENGINEERING-PRINCIPLES.md significantly improves navigability and discoverability of important documentation.
CLAUDE.md (736-737)
Updating the descriptions for engineering-principles.md and thought-transparency.md in the modular rules section provides a clearer understanding of their content and purpose.
docs/ARCHITECTURE.md (28-30)
Adding CODEOWNERS and dependabot.yml to the .github/ directory tree provides a more accurate representation of the repository's structure and configuration.
docs/ARCHITECTURE.md (36)
Adding trigger-docs.yml to the workflows/ directory is an important update, documenting the cross-repo documentation rebuild trigger.
docs/ARCHITECTURE.md (49-55)
Including ENGINEERING-PRINCIPLES.md and designs/ in the docs/ directory tree, along with updated descriptions for WORKFLOWS.md, provides a more complete and accurate overview of the documentation structure.
docs/ARCHITECTURE.md (103-111)
The addition of "Passive context layers" is a significant improvement, clearly explaining how different documentation elements contribute to the agent's understanding and providing guidance on when to use each layer.
docs/ARCHITECTURE.md (147-149)
The updated explanation of AI coordination, distinguishing between Claude's passive context and other AIs' shared files, provides a clearer understanding of how different agents interact.
docs/PLUGINS.md (7-20)
Adding an example of how to declare capabilities in plugin.json is very helpful for plugin developers, providing a clear template for specifying skills, commands, agents, and hooks.
docs/QUICK-REFERENCE.md (84-85)
Clarifying that eight-gates and hades are skills, not slash commands, and explaining how to invoke them via the Skill tool, is crucial for correct usage and understanding.
docs/WORKFLOWS.md (64)
The note about the commit-integrity-hook automatically blocking certain commits is a valuable addition, informing users that manual checks are not needed for these specific cases.
docs/WORKFLOWS.md (81-87)
Adding a dedicated section for the "Cross-repo docs trigger" with details about trigger-docs.yml, its requirements, and cross-repo dependency, is excellent documentation for maintaining the documentation site.
![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: 894cc76983
ℹ️ 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".
| "hooks": "hooks/hooks.json" | ||
| } | ||
| ``` | ||
| > **Note:** `hooks/hooks.json` is loaded by Claude Code when declared in `plugin.json`. |
There was a problem hiding this comment.
This guidance is incorrect for this repo’s plugin model: the ground-truth assertions explicitly state hooks/hooks.json is auto-discovered and that declaring a hooks field in plugin.json causes duplicate-load errors (plugins/metacognitive-guard/blackboard/assertions.yaml and plugins/metacognitive-guard/hooks/scripts/truth-beacon.sh). Keeping this new example will cause new plugins to be scaffolded with a manifest shape that can break hook loading at runtime.
Useful? React with 👍 / 👎.
|
|
||
| Before committing changes: | ||
|
|
||
| > **Note:** The `commit-integrity-hook` (metacognitive-guard) automatically blocks commits containing warning suppressions or commented-out tests. No manual check needed for these — the hook enforces it. |
There was a problem hiding this comment.
The new note says no manual check is needed because commit-integrity-hook automatically blocks bad commits, but that hook is configured only for Claude’s PreToolUse Bash event (see plugins/metacognitive-guard/hooks/hooks.json) and is not a Git pre-commit hook. In normal local Git usage this protection does not run, so this wording can cause contributors to skip checks that are still required outside Claude sessions.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Pull request overview
Documentation-focused PR that cleans up duplicated/contradictory guidance in the repo’s auto-loaded Claude rules and the docs/ reference set, aiming to reduce passive-context bloat and improve accuracy/modernization.
Changes:
- Removed the duplicated
.claude/rules/engineering-philosophy.mdrule file and updatedCHANGELOG.mdto reflect the audit-finding cleanup. - Updated core docs (
ARCHITECTURE.md,WORKFLOWS.md,QUICK-REFERENCE.md,PLUGINS.md,CLAUDE.md) for corrected paths, new workflow documentation, and clarified command/skill usage. - Simplified and corrected several
.claude/rules/*files (SOLID, error handling, CALMS/DORA, engineering principles, thought transparency) to remove contradictions and improve signal.
Reviewed changes
Copilot reviewed 12 out of 12 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/WORKFLOWS.md | Adds commit checklist note + documents cross-repo docs trigger workflow |
| docs/QUICK-REFERENCE.md | Adds /hookify:help and clarifies Exodia skills vs commands |
| docs/PLUGINS.md | Updates plugin creation instructions and adds capability declaration example |
| docs/ARCHITECTURE.md | Fixes repo tree and documents passive context layers; replaces duplicated sections with pointers |
| CLAUDE.md | Replaces large trees with pointers; expands routing tree; centralizes doc pointers |
| CHANGELOG.md | Records removal/changes related to the audit-finding cleanup |
| .claude/rules/thought-transparency.md | Removes sequential-only decomposition section that contradicts parallel-lane guidance |
| .claude/rules/solid-principles.md | Compresses SOLID guidance into a table + shorter statements |
| .claude/rules/error-handling.md | Replaces “retry with backoff” guidance with re-run-after-fix escalation |
| .claude/rules/engineering-principles.md | Fixes duplicated principle tag (#25 → #25b) |
| .claude/rules/devops-calms.md | Clarifies Claude vs external-AI coordination channels; standardizes MTTR label |
| .claude/rules/engineering-philosophy.md | Deleted as duplicate to reduce passive-context token overhead |
| ### Changed | ||
|
|
||
| - **`thought-transparency.md`**: Removed "Granular Task Decomposition" section (contradicted LAW 3 parallel execution) and duplicate "Silent Processing" section | ||
| - **`devops-calms.md`**: Fixed AGENTS.md incorrectly listed as Claude coordination channel; separated Claude channels (`CLAUDE.md`, `.claude/rules/`, `SKILL.md`, SessionStart hooks) from external-AI channels (`AGENTS.md`, `copilot-instructions.md`); standardized "Recovery Time" → "MTTR" | ||
| - **`solid-principles.md`**: Compressed from 49 to ~25 lines; replaced bullet list with responsibility table; fixed metacognitive-guard SRP description |
There was a problem hiding this comment.
CHANGELOG.md now has two ### Changed sections under [Unreleased] (one newly added here and an existing one later). Consider merging into the existing headings to keep a single set of sections per Keep-a-Changelog style, and reconcile the new removal note with the older [Unreleased] entry that says engineering-philosophy.md was added.
|
|
||
| Before committing changes: | ||
|
|
||
| > **Note:** The `commit-integrity-hook` (metacognitive-guard) automatically blocks commits containing warning suppressions or commented-out tests. No manual check needed for these — the hook enforces it. |
There was a problem hiding this comment.
The note implies the commit-integrity hook blocks commits in general, but it only runs inside Claude Code as a PreToolUse hook on the Bash tool (i.e., when Claude executes git commit). For human/local commits outside Claude Code, this enforcement won’t run—please clarify the scope so the pre-commit checklist is accurate.
| > **Note:** The `commit-integrity-hook` (metacognitive-guard) automatically blocks commits containing warning suppressions or commented-out tests. No manual check needed for these — the hook enforces it. | |
| > **Note:** The `commit-integrity-hook` (metacognitive-guard) runs only inside Claude Code as a PreToolUse hook on the Bash tool (i.e., when Claude executes `git commit`). It does **not** affect human/local `git commit` commands. When committing locally, you are still responsible for checking for warning suppressions or commented-out tests (or configuring your own local git hook) before pushing. |
| `.github/workflows/trigger-docs.yml` runs on every push to `main` and triggers a rebuild of the `ancplua-docs` documentation site. | ||
|
|
||
| **Requires:** `DOCS_TRIGGER_PAT` secret (a GitHub PAT with `repo` scope on the `ancplua-docs` repository). | ||
|
|
||
| **Cross-repo dependency:** Changes to plugin docs, SKILL.md files, or README files in this repo will automatically propagate to the docs site after merge. |
There was a problem hiding this comment.
This section says trigger-docs.yml runs on every push to main, but the workflow also triggers on release.published and workflow_dispatch. Please update the description so it matches the actual workflow triggers.
| 2. Add `.claude-plugin/plugin.json` with at least `name`, `version`, `description`, `author`. | ||
| 3. Optionally declare capabilities in `plugin.json`: | ||
| ```json | ||
| { | ||
| "name": "my-plugin", | ||
| "version": "1.0.0", | ||
| "description": "...", | ||
| "author": "...", |
There was a problem hiding this comment.
These instructions say plugin.json only needs name, version, description, author, but the repo’s plugin template and existing plugins also include repository and license. To keep repo docs consistent with how plugins are authored here, either list those fields as required (repo convention) or explicitly call them out as strongly recommended.
| 2. Add `.claude-plugin/plugin.json` with at least `name`, `version`, `description`, `author`. | |
| 3. Optionally declare capabilities in `plugin.json`: | |
| ```json | |
| { | |
| "name": "my-plugin", | |
| "version": "1.0.0", | |
| "description": "...", | |
| "author": "...", | |
| 2. Add `.claude-plugin/plugin.json` with at least `name`, `version`, `description`, `author`, `license`. Including a `repository` field is strongly recommended. | |
| 3. Optionally declare capabilities in `plugin.json` (example also shows `repository` and `license` fields): | |
| ```json | |
| { | |
| "name": "my-plugin", | |
| "version": "1.0.0", | |
| "description": "...", | |
| "author": "...", | |
| "repository": "https://github.com/example/my-plugin", | |
| "license": "MIT", |
| "skills": ["skills/my-skill"], | ||
| "commands": ["commands/my-command.md"], | ||
| "agents": ["agents/my-agent.md"], | ||
| "hooks": "hooks/hooks.json" | ||
| } | ||
| ``` | ||
| > **Note:** `hooks/hooks.json` is loaded by Claude Code when declared in `plugin.json`. |
There was a problem hiding this comment.
The plugin.json example doesn’t match the manifests used in this repo: plugins typically set commands/skills to a directory string (e.g. "./commands"), and none of the current plugin.json files declare a hooks field. Either adjust the example to reflect the repo’s current manifest pattern, or update the plugin manifests if the docs are intentionally switching to a new schema.
| "skills": ["skills/my-skill"], | |
| "commands": ["commands/my-command.md"], | |
| "agents": ["agents/my-agent.md"], | |
| "hooks": "hooks/hooks.json" | |
| } | |
| ``` | |
| > **Note:** `hooks/hooks.json` is loaded by Claude Code when declared in `plugin.json`. | |
| "skills": "./skills", | |
| "commands": "./commands", | |
| "agents": "./agents" | |
| } |
Note: By convention, event hooks live at
hooks/hooks.jsonand are loaded by Claude Code when present.
| │ └── <agent>.md # Custom agent definitions (YAML frontmatter) | ||
| ├── hooks/ | ||
| │ └── hooks.json # Event hooks (auto-loaded by convention) | ||
| │ └── hooks.json # Event hooks (declared in plugin.json, loaded by Claude Code) |
There was a problem hiding this comment.
This line says hooks are "declared in plugin.json", but the repo’s plugin manifests don’t include a hooks field even when hooks/hooks.json exists. Please either revert this to the current convention (hooks.json discovered/loaded by convention) or update manifests/docs consistently.
| │ └── hooks.json # Event hooks (declared in plugin.json, loaded by Claude Code) | |
| │ └── hooks.json # Event hooks (discovered by convention and loaded by Claude Code) |
| ``` | ||
| See `docs/ARCHITECTURE.md` Section 3 for the full plugin structure and passive context layer documentation. | ||
|
|
||
| **Required:** `.claude-plugin/plugin.json` (fields: `name`, `version`, `description`, `author`) + `README.md` |
There was a problem hiding this comment.
This claims .claude-plugin/plugin.json only requires name, version, description, author, but the repo’s plugin template and all current plugins also include repository and license. For consistency, either include those in the required (repo-convention) field list or clarify that they’re optional per upstream but required by this repo’s template/marketplace expectations.
| **Required:** `.claude-plugin/plugin.json` (fields: `name`, `version`, `description`, `author`) + `README.md` | |
| **Required:** `.claude-plugin/plugin.json` + `README.md`. Upstream Claude Code requires at minimum `name`, `version`, `description`, and `author`; this repo’s plugin template and marketplace additionally require `license` and `repository`. |
Summary
engineering-philosophy.md— P0 duplicate ofengineering-principles.md(~900 tokens/session wasted)thought-transparency.md— removed sequential-execution clause contradicting LAW 3 (parallel lanes).claude/rules/anddocs/covering accuracy, deduplication, and modernization findingsChanges by category
Removed (1 file):
.claude/rules/engineering-philosophy.md— complete duplicate, both auto-loaded, ~1950 tokens wasted per sessionRules fixes (5 files):
devops-calms.md: Claude vs external-AI channels split; MTTR standardizedengineering-principles.md: duplicate fix(ci): graceful skip for Claude workflow self-review #25 tag fixed → #25bsolid-principles.md: compressed to table; metacognitive-guard SRP description fixederror-handling.md: retry-with-backoff replaced with re-run-after-fixthought-transparency.md: sequential prohibition removed (contradicts LAW 3)Docs fixes (4 files):
ARCHITECTURE.md: directory tree corrected; passive context layers documented; Section 5/7 replaced with pointers; coordination channels fixed; Last Verified updatedWORKFLOWS.md: trigger-docs.yml section added; commit-integrity-hook added to checklistQUICK-REFERENCE.md: /hookify:help added; eight-gates/hades clarified as skills; hades agent count fixedPLUGINS.md: fake required fields removed; capability declaration fields addedCLAUDE.md (1 file):
Test plan
./tooling/scripts/weave-validate.shpasses (0 hard failures)claude plugin validate .passes🤖 Generated with Claude Code
Summary by CodeRabbit
Release Notes
New Features
Documentation