Merge pull request #248 from mvanhorn/osc/199-fix-agent-namespace

fix(commands): use fully-qualified agent namespace in Task invocations

Author: tmchow

AGENTS.md

@@ -48,6 +48,16 @@ Add a new provider when at least one of these is true:
 
 Avoid adding a provider if the target spec is unstable or undocumented.
 
+## Agent References in Skills
+
+When referencing agents from within skill SKILL.md files (e.g., via the `Agent` or `Task` tool), always use the **fully-qualified namespace**: `compound-engineering:<category>:<agent-name>`. Never use the short agent name alone.
+
+Example:
+- `compound-engineering:research:learnings-researcher` (correct)
+- `learnings-researcher` (wrong - will fail to resolve at runtime)
+
+This prevents resolution failures when the plugin is installed alongside other plugins that may define agents with the same short name.
+
 ## Repository Docs Convention
 
 - **Plans** live in `docs/plans/` and track implementation progress.

plugins/compound-engineering/skills/ce-brainstorm/SKILL.md

@@ -41,7 +41,7 @@ Use **AskUserQuestion tool** to suggest: "Your requirements seem detailed enough
 
 Run a quick repo scan to understand existing patterns:
 
-- Task repo-research-analyst("Understand existing patterns related to: <feature_description>")
+- Task compound-engineering:research:repo-research-analyst("Understand existing patterns related to: <feature_description>")
 
 Focus on: similar features, established patterns, CLAUDE.md guidance.
 

plugins/compound-engineering/skills/ce-plan/SKILL.md

@@ -82,8 +82,8 @@ First, I need to understand the project's conventions, existing patterns, and an
 
 Run these agents **in parallel** to gather local context:
 
-- Task repo-research-analyst(feature_description)
-- Task learnings-researcher(feature_description)
+- Task compound-engineering:research:repo-research-analyst(feature_description)
+- Task compound-engineering:research:learnings-researcher(feature_description)
 
 **What to look for:**
 - **Repo research:** existing patterns, CLAUDE.md guidance, technology familiarity, pattern consistency
@@ -113,8 +113,8 @@ Examples:
 
 Run these agents in parallel:
 
-- Task best-practices-researcher(feature_description)
-- Task framework-docs-researcher(feature_description)
+- Task compound-engineering:research:best-practices-researcher(feature_description)
+- Task compound-engineering:research:framework-docs-researcher(feature_description)
 
 ### 1.6. Consolidate Research
 

plugins/compound-engineering/skills/ce-review/SKILL.md

@@ -109,8 +109,8 @@ For each agent in review_agents:
 ```
 
 Always run these last regardless of mode:
-- Task agent-native-reviewer(PR content) - Verify new features are agent-accessible
-- Task learnings-researcher(PR content) - Search docs/solutions/ for past issues related to this PR's modules and patterns
+- Task compound-engineering:review:agent-native-reviewer(PR content) - Verify new features are agent-accessible
+- Task compound-engineering:research:learnings-researcher(PR content) - Search docs/solutions/ for past issues related to this PR's modules and patterns
 
 </parallel_tasks>
 
@@ -122,9 +122,9 @@ These agents are run ONLY when the PR matches specific criteria. Check the PR fi
 
 **MIGRATIONS: If PR contains database migrations, schema.rb, or data backfills:**
 
-- Task schema-drift-detector(PR content) - Detects unrelated schema.rb changes by cross-referencing against included migrations (run FIRST)
-- Task data-migration-expert(PR content) - Validates ID mappings match production, checks for swapped values, verifies rollback safety
-- Task deployment-verification-agent(PR content) - Creates Go/No-Go deployment checklist with SQL verification queries
+- Task compound-engineering:review:schema-drift-detector(PR content) - Detects unrelated schema.rb changes by cross-referencing against included migrations (run FIRST)
+- Task compound-engineering:review:data-migration-expert(PR content) - Validates ID mappings match production, checks for swapped values, verifies rollback safety
+- Task compound-engineering:review:deployment-verification-agent(PR content) - Creates Go/No-Go deployment checklist with SQL verification queries
 
 **When to run:**
 - PR includes files matching `db/migrate/*.rb` or `db/schema.rb`
@@ -236,7 +236,7 @@ Complete system context map with component interactions
 
 ### 4. Simplification and Minimalism Review
 
-Run the Task code-simplicity-reviewer() to see if we can simplify the code.
+Run the Task compound-engineering:review:code-simplicity-reviewer() to see if we can simplify the code.
 
 ### 5. Findings Synthesis and Todo Creation Using file-todos Skill