Multiple documentation and metadata inconsistencies in compounding-engineering plugin

[baslogic]

Summary

During a systematic audit of the compounding-engineering plugin, I discovered multiple critical inconsistencies between claimed capabilities and actual implementation. These issues prevent the plugin from working correctly and mislead users about available features.

Environment

• Plugin location: plugins/compounding-engineering/
• Plugin version: 1.0.0
• Discovery method: Manual file system audit

Critical Issues

🔴 1. Incorrect Agent Count in Metadata

Files affected:

• plugins/compounding-engineering/.claude-plugin/plugin.json:4
• .claude-plugin/marketplace.json:14

Claimed: "15 specialized agents"
Actual: 17 agent files exist

Actual agents present:

1. architecture-strategist.md
2. best-practices-researcher.md
3. code-simplicity-reviewer.md
4. data-integrity-guardian.md
5. dhh-rails-reviewer.md
6. every-style-editor.md
7. feedback-codifier.md
8. framework-docs-researcher.md
9. git-history-analyzer.md
10. kieran-python-reviewer.md
11. kieran-rails-reviewer.md
12. kieran-typescript-reviewer.md
13. pattern-recognition-specialist.md
14. performance-oracle.md
15. pr-comment-resolver.md
16. repo-research-analyst.md
17. security-sentinel.md

Impact: Users are misled about plugin capabilities.

---

🔴 2. Missing Referenced Agents (BREAKS /review COMMAND)

File: plugins/compounding-engineering/commands/review.md

The /review command references four agents that do not exist:

• rails-turbo-expert - referenced at line ~85
• dependency-detective - referenced at line ~88
• code-philosopher - referenced at line ~91
• devops-harmony-analyst - referenced at line ~94

Impact: The /review command will fail when attempting to invoke these non-existent agents via the Task tool.

Error users will see: "Agent not found" or similar when running /review

---

🔴 3. Missing README.md

Expected location: plugins/compounding-engineering/README.md
Status: Does not exist

Referenced in: Parent repository CLAUDE.md line 8 explicitly shows this file should exist in the plugin structure

Impact:

• No usage documentation for the plugin
• Users don't know how to use the commands
• No examples of agent invocation
• New users have to read source code to understand features (as noted in issue [Doc Request] Compound Engineering plugin intended usage #3)

---

Moderate Issues

🟡 4. CHANGELOG.md Completely Out of Sync

File: plugins/compounding-engineering/CHANGELOG.md

Discrepancies:

Agents:

• Claims "21 total agents" (actual: 17)
• Lists non-existent agents:
  • cora-test-reviewer
  • lint
  • bug-reproduction-validator
  • assistant-component-creator
  • ahoy-tracking-expert
  • appsignal-log-investigator

Commands:

• Claims "24 total commands" (actual: 6)
• Lists 18 non-existent commands including:
  • /code-review, /review_relevant, /test, /reproduce-bug
  • /prepare_pr, /resolve_pr_parallel, /cleanup
  • /create-developer-doc, /update-help-center, /changelog
  • And 12 more...

Impact: CHANGELOG is completely unreliable and misleads contributors and users.

---

🟡 5. Parent Repository Documentation References Removed Features

File: Repository root CLAUDE.md line 8

Shows this structure:

└── compounding-engineering/
    ├── agents/                # 15 specialized AI agents
    ├── commands/              # 6 slash commands
    ├── hooks/                 # 2 automated hooks
    └── README.md              # Plugin documentation

Issues:

• Hooks directory doesn't exist (was deliberately removed per CHANGELOG)
• README.md doesn't exist
• Agent count is wrong (should be 17)

---

Correct Information

✅ Command Count is Accurate

Claimed: 6 commands
Actual: 6 commands exist

Commands:

1. generate_command.md
2. plan.md
3. resolve_todo_parallel.md
4. review.md
5. triage.md
6. work.md

---

Verification Commands

To reproduce these findings:

# Count agents
ls -1 plugins/compounding-engineering/agents/*.md | wc -l
# Returns: 17

# Count commands
ls -1 plugins/compounding-engineering/commands/*.md | wc -l
# Returns: 6

# Check for README
ls plugins/compounding-engineering/README.md
# Returns: No such file or directory

# Check for missing agents in review.md
grep -E "rails-turbo-expert|dependency-detective|code-philosopher|devops-harmony-analyst" \
  plugins/compounding-engineering/commands/review.md
# Shows 4 references to non-existent agents

---

Suggested Fixes

Priority 1 (Breaks functionality):

1. Fix /review command: Remove references to non-existent agents OR create the 4 missing agents
2. Create README.md: Add comprehensive usage documentation with examples

Priority 2 (Misleading metadata):

3. Update plugin.json: Change description to "17 specialized agents"
4. Update marketplace.json: Change description to "17 specialized agents"
5. Update CHANGELOG.md: Remove all non-existent agents and commands, reflect actual state

Priority 3 (Documentation cleanup):

6. Update repository CLAUDE.md: Remove hooks reference, fix agent count

---

Related Issues

• [Doc Request] Compound Engineering plugin intended usage #3 - "Compound Engineering plugin intended usage" - Users asking how to use the plugin (no README)

---

Additional Context

This audit was performed by examining the actual file system at:
/Users/[user]/.claude/plugins/marketplaces/every-marketplace/plugins/compounding-engineering/

All findings are based on comparing:

• Claimed capabilities (plugin.json, marketplace.json, CHANGELOG.md)
• Actual files present (agents/, commands/ directories)
• Command source code (references to agents)

The plugin has excellent potential, but these inconsistencies need resolution for users to effectively use it.

[kieranklaassen]

I'll update this.