fix: make the plugin actually load in Claude Code (invalid manifest, wrong layout, unsupported install)

[deniscms]

Problem

After a clean git clone + ./install.sh, nothing this repo ships reaches Claude Code. /grow does not register, and neither does any of the agents. The README's troubleshooting steps ("confirm the symlink", "confirm the manifest") all pass while the plugin remains entirely absent, which makes the failure very hard to diagnose.

Three separate defects, all confirmed with claude plugin validate.

1. The manifest is invalid

.claude-plugin/plugin.json declared commands, agents, skills and hooks as arrays of objects ([{"path": "..."}]), a shape the schema rejects, plus mcp-servers instead of mcpServers:

✘ Found 4 errors:
  ❯ plugins[0] plugin.json → hooks: Invalid input
  ❯ plugins[0] plugin.json → commands: Invalid input
  ❯ plugins[0] plugin.json → agents: Invalid input
  ❯ plugins[0] plugin.json → skills: Invalid input

⚠ plugins[0] plugin.json → mcp-servers: Unknown field 'mcp-servers' — did you mean 'mcpServers'?

2. The file layout does not match what Claude Code discovers

Claude Code discovers components by convention: commands/<name>.md, agents/<name>.md, skills/<name>/SKILL.md. This repo had commands/grow/COMMAND.md and agents/<n>/AGENT.md, so zero commands and zero agents were found. (Only skills/ was already correct, which is why skills were the one thing that loaded.)

Worth recording: pointing the manifest at those nested paths explicitly — "agents": ["./agents/cmo/AGENT.md", ...] — passes validation but still yields Agents (0). Only the conventional layout actually works.

3. install.sh used an unsupported install method

The script symlinked the clone into ~/.claude/plugins/growthOS. That directory is Claude Code's own managed state (cache/, marketplaces/, installed_plugins.json) — not a discovery path. The symlink had no effect; the plugin never appeared in installed_plugins.json and no enabledPlugins entry was ever written.

A plugin is discovered only once it is registered as a marketplace and installed from it — and this repo already ships .claude-plugin/marketplace.json for exactly that, so the fix is two commands.

Changes

• commands/grow/COMMAND.md → commands/grow.md; supporting docs (setup.md, FREE-CONTENT.md) moved to docs/grow/, references updated.
• agents/<n>/AGENT.md → agents/<n>.md (12 agents); per-agent README.md / router.md moved to docs/agents/<n>/ so they are not mistaken for agent definitions.
• Manifest reduced to the valid schema, relying on convention-based discovery.
• Duplicate root plugin.json removed — Claude Code reads only .claude-plugin/plugin.json, and the two had already drifted apart (11 agents / 26 skills vs 9 / 20).
• install.sh rewritten around claude plugin marketplace add + claude plugin install, validating the manifest first and removing the symlink older versions left behind.
• README: installation, uninstall and troubleshooting rewritten around commands that report real state (claude plugin list / details / validate); architecture tree corrected.

No agent, skill or command content was changed — this is manifest, layout and install only.

Verification

Before:

Skills (26)  competitive-intelligence, content-creation, ...
Agents (0)

After:

$ claude plugin details growthOS
Component inventory
  Skills (27)  ..., grow, ...
  Agents (12)  caption-writer, carousel-designer, cmo, content-creator,
               growth-engineer, growth-strategist, intelligence-analyst,
               sales-page-architect, sales-page-qa, social-publisher,
               video-producer, visual-designer

$ claude plugin list
  ❯ growthOS@growthOS
    Status: ✔ enabled

$ claude plugin validate .
✔ Validation passed with warnings

The one remaining warning is cosmetic: the plugin name growthOS is not kebab-case, which only matters for Claude.ai marketplace sync. Left alone deliberately — renaming it would change the plugin id users already have installed.

Known, still unwired (deliberately out of scope)

• Hooks (0) — the four hooks/*.md files are prose, not hook configuration. Claude Code expects hooks as JSON in plugin.json (matcher + command). Converting them requires deciding what each hook should actually execute, which is a design call for the maintainer, not a mechanical fix.
• MCP servers (0) — the four Python servers exist but there is no mcpServers entry and no .mcp.json. Wiring them needs the launch command and credential handling.

Happy to follow up with either in a separate PR if you want to point me at the intended behaviour.