Running /workflows:compound after a long session fails to find the agent type `compound-engineering:workflow:compound-docs`

[zackintosh]

When running the /workflows:compound command in a CLI it fails to find the `'compound-engineering:workflow:compound-docs' agent.

I'm on plugin version 2.28.0 and Claude Code version 2.1.25

Here is the output:

/workflows:compound

⏺ I'll coordinate multiple subagents working in parallel to document the fishing event currency duplication fix we just implemented.

⏺ compound-engineering:workflow:compound-docs(Document fishing event currency fix)
  ⎿  Initializing…
  ⎿  Error: Agent type 'compound-engineering:workflow:compound-docs' not found. Available agents: Bash, general-purpose, statusline-setup, Explore, Plan,
     claude-code-guide, compound-engineering:research:framework-docs-researcher, compound-engineering:research:learnings-researcher,
     compound-engineering:research:best-practices-researcher, compound-engineering:research:git-history-analyzer,
     compound-engineering:research:repo-research-analyst, compound-engineering:design:figma-design-sync,
     compound-engineering:design:design-implementation-reviewer, compound-engineering:design:design-iterator, compound-engineering:docs:ankane-readme-writer,
     compound-engineering:review:kieran-rails-reviewer, compound-engineering:review:pattern-recognition-specialist,
     compound-engineering:review:kieran-python-reviewer, compound-engineering:review:kieran-typescript-reviewer,
     compound-engineering:review:performance-oracle, compound-engineering:review:security-sentinel, compound-engineering:review:deployment-verification-agent,
     compound-engineering:review:code-simplicity-reviewer, compound-engineering:review:data-migration-expert,
     compound-engineering:review:julik-frontend-races-reviewer, compound-engineering:review:architecture-strategist,
     compound-engineering:review:dhh-rails-reviewer, compound-engineering:review:data-integrity-guardian, compound-engineering:review:agent-native-reviewer,
     compound-engineering:workflow:every-style-editor, compound-engineering:workflow:lint, compound-engineering:workflow:pr-comment-resolver,
     compound-engineering:workflow:bug-reproduction-validator, compound-engineering:workflow:spec-flow-analyzer


⏺ The compound-docs agent isn't available in this environment. Let me create the documentation manually following the compound documentation pattern:

[Yash-xoxo]

Hey @zackintosh,

The compound-docs agent is missing from the available agents list - it's probably an issue with how the agent is registered or loaded.

Quick Checks

1. Verify the agent file exists:

ls -la ~/.claude/plugins/compound-engineering/agents/workflow/compound-docs.md

2. Check if it's actually a skill, not an agent:
   Looking at issue Agent files for skill-only components waste tokens and error on invocation #156, some workflow components are incorrectly placed in agents/ when they should be skills. If compound-docs.md lacks proper agent persona config, it won't load.

3. Try refreshing the plugin:

# Force reinstall
npm uninstall -g @every/compound-engineering
npm install -g @every/compound-engineering@latest

Likely Cause

Based on the error and #156, compound-docs might be:

• A skill masquerading as an agent (missing persona config)
• Not properly exported in the plugin's agent registry
• Corrupted in your local plugin cache

Workaround

For now, use the Skill tool instead:

/skill compound-engineering:compound-docs

If that works, then it confirms it's a skill-vs-agent registration issue.

Let me know if the file exists and what the frontmatter looks like - that'll confirm the root cause.

[zackintosh]

Hey @Yash-xoxo,

The agent file doesn't exist at ~/.claude/plugins/compound-engineering/agents/workflow/compound-docs.md because it looks like each plugin install is versioned in the cache folder like so: ~/.claude/plugins/cache/every-marketplace/compound-engineering/2.31.1/

I am on version 2.31.1 and the compound-docs.md file doesn't exits at ~/.claude/plugins/cache/every-marketplace/compound-engineering/2.31.1/agents/workflow/compound-docs.md for me either. The contents of that directory is as follows:

• bug-reproduction-validator.md
• every-style-editor.md
• lint.md
• pr-comment-resolver.md
• spec-flow-analyzer.md

If you look at that folder in the repo, those are the exact files I have with no sign of the compound-docs.md file in that directory: https://github.com/EveryInc/compound-engineering-plugin/tree/main/plugins/compound-engineering/agents/workflow

[Yash-xoxo]

Hey @zackintosh,

Thanks for the detailed investigation! You've identified the root cause perfectly.

The Real Issue

You're right - compound-docs.md doesn't exist in the repository. Looking at the [workflow agents directory](https://github.com/EveryInc/compound-engineering-plugin/tree/main/plugins/compound-engineering/agents/workflow), there are only 5 files:

• bug-reproduction-validator.md ✅
• every-style-editor.md ✅
• lint.md ✅
• pr-comment-resolver.md ✅
• spec-flow-analyzer.md ✅

No compound-docs.md.

Why /workflows:compound References It

The /workflows:compound command is trying to spawn compound-engineering:workflow:compound-docs but that agent was never created. This is likely:

1. Planned but not implemented - the workflow references it, but the agent file was never added
2. Removed in a refactor - maybe it existed before and got deleted
3. Should be a skill, not an agent - similar to issue Agent files for skill-only components waste tokens and error on invocation #156

Looking at PR #149

@terry-li-hm's commit 32052d4 claims to "add missing compound-docs agent persona" but I don't see a corresponding file in the repo. The PR might not have been merged, or the commit didn't include the actual file.

Immediate Fix Options

Option 1: Use a Different Documentation Agent

The repo has ankane-readme-writer in docs/:

/skill compound-engineering:docs:ankane-readme-writer

This might serve the same purpose.

Option 2: Create the Missing Agent

Based on the pattern of other workflow agents, here's what compound-docs.md should probably look like:

---
name: compound-docs
description: "Documents code changes, features, and fixes following compound documentation patterns. Use when changes need to be documented for internal reference or external communication."
model: inherit
---

<examples>
<example>
Context: User has just implemented a bug fix that needs documentation.
user: "I just fixed the fishing event currency duplication bug"
assistant: "Let me use compound-docs to document this fix properly"
<commentary>A code change needs documentation, so use compound-docs agent.</commentary>
</example>
</examples>

You are a technical documentation specialist following compound's documentation standards...
[rest of agent definition]

Option 3: Fix the Workflow

Update /workflows:compound to not reference the non-existent agent. Instead, handle documentation inline or use an existing agent.

Recommended Action

For maintainers (@kieranklaassen):

1. Either:

   • Add compound-docs.md to the repo (and include in PR fix: add missing compound-docs agent persona #149 properly)
   • OR update /workflows:compound to use ankane-readme-writer or handle docs differently

2. Clean up agent vs skill confusion:

   • Audit all workflow commands to ensure they only reference agents that exist
   • Move any documentation-only components to skills if they don't need agent spawning

For @zackintosh (immediate workaround):

Try using the existing docs agent:

# Instead of /workflows:compound
# Use the skill directly:
/skill compound-engineering:docs:ankane-readme-writer

Or manually invoke the workflow steps without the missing agent.

Root Cause Summary

The compound-docs agent doesn't exist in the repository at all. The /workflows:compound command references it, but it was never implemented (or was removed). This needs to be fixed either by:

• Creating the missing agent file
• Updating the workflow to use existing agents
• Moving documentation to a skill instead of an agent

[kieranklaassen]

compound-docs is a skill, not an agent — it cannot be invoked via Task. The /workflows:compound command IS the compound-docs workflow and invokes it inline. No Task compound-engineering:workflow:compound-docs call exists in the current codebase. If you're still seeing this error, please share which specific command triggered it.