fix: ensure commands immediately delegate to agents

[johnrogers]

Commands were not emphasizing immediate agent invocation strongly enough, leading to Claude using EnterPlanMode or direct tool usage instead.

Updated all commands to match the /feature pattern with:

• Explicit "IMMEDIATELY Invoke Agent" sections
• Clear Task() call examples
• Strong warnings against EnterPlanMode and direct tool usage

This ensures proper delegation to specialized agents for all workflows.

[claude]

Code Review - PR #5: Fix Command Agent Delegation

Overview

This PR improves command files to ensure they immediately delegate to specialized agents rather than using EnterPlanMode or direct tool usage. The changes are consistent and well-structured.

---

✅ Strengths

1. Consistent Pattern Application

All five command files now follow a uniform structure with clear "IMMEDIATELY Invoke Agent" sections. This consistency makes the codebase more maintainable and predictable.

2. Clear Documentation

The new sections include:

• Explicit code examples showing the Task() call syntax
• Strong warnings against anti-patterns (EnterPlanMode, direct tool usage)
• Context about what the agent does and why it should be used

3. Good Section Organization

The step numbering was properly updated throughout all files, maintaining logical flow despite the insertion of new content.

4. Comprehensive Coverage

The changes address all command workflows:

• /build - delegates to swift-builder
• /modernize - delegates to swift-modernizer
• /plan - delegates to swift-ui-design or swift-architect
• /review - delegates to swift-code-reviewer
• /test - delegates to swift-test-creator or swift-builder

---

📝 Observations & Suggestions

1. Duplicated Warning Blocks

All command files have the same warning block at the top:

> ⛔ **DO NOT use Claude's built-in Plan mode**
>
> This command uses specialized agents:
> - Planning: `@swift-architect`, `@tca-architect`
> - Implementation: `@swift-engineer`, `@tca-engineer`, `@swiftui-specialist`

Observation: The agent list is generic across all commands, even though some commands don't use all these agents. For example:

• /build only uses @swift-builder (and potentially implementation agents for fixes)
• /modernize only uses @swift-modernizer
• /review only uses @swift-code-reviewer

Suggestion: Consider customizing the warning block per command to list only the relevant agents, or simplify to a more generic message.

2. plan.md Additional Context

In plan.md:72-84, there's a unique section that provides analysis suggestions before the "IMMEDIATELY Invoke" section. This is good, but it creates a slight inconsistency with other commands.

Observation: This section tells Claude to analyze and ask questions before invoking the agent, which seems appropriate for planning but differs from other commands.

Suggestion: This is actually fine as-is since planning requires more upfront clarification. Just noting it for awareness.

3. Error Recovery Paths

The commands mention what to do if agent tasks fail (e.g., in build.md it hands off to specialist agents after 3 attempts), but the new "IMMEDIATELY Invoke" sections don't mention these fallback patterns.

Observation: This is likely fine since the fallback logic is covered in later sections.

Suggestion: No change needed, but worth confirming that agents understand the full error recovery workflow.

---

🔍 Code Quality Assessment

Documentation Quality: ⭐⭐⭐⭐⭐

• Clear, actionable instructions
• Good use of formatting (code blocks, warnings, examples)
• Consistent voice and structure

Consistency: ⭐⭐⭐⭐⭐

• All five files follow the same pattern
• Step numbering properly maintained
• Warning blocks identical (see note above)

Completeness: ⭐⭐⭐⭐⭐

• All command workflows addressed
• Both conditional paths covered (e.g., UI vs no-UI in plan.md)
• Clear examples of Task() invocation syntax

---

🐛 Potential Issues

None Found

No bugs, security concerns, or performance issues identified. This is documentation-only changes with no executable code.

---

🧪 Test Coverage

Not Applicable: This PR only modifies markdown documentation files. No tests are needed.

Verification Recommendation: Manual testing would involve:

1. Running each command (/build, /modernize, /plan, /review, /test)
2. Verifying that Claude immediately invokes the specified agent
3. Confirming that Claude doesn't use EnterPlanMode or direct tools

---

📊 Impact Assessment

Risk Level: LOW

• Documentation-only changes
• No breaking changes to existing functionality
• Improves clarity and reduces confusion

Benefits:

• ✅ Reduces incorrect behavior (using EnterPlanMode instead of agents)
• ✅ Makes agent delegation pattern explicit and clear
• ✅ Improves developer/user understanding of workflow
• ✅ Sets clear expectations for Claude's behavior

---

✅ Recommendation

APPROVE - This PR successfully addresses its stated goal of ensuring commands immediately delegate to agents. The changes are well-structured, consistent, and improve the clarity of the command workflows.

Optional Follow-ups (not blocking):

1. Consider customizing the warning block per command to list only relevant agents
2. Add a central documentation page explaining the agent delegation pattern (if one doesn't exist)
3. Consider adding examples of what NOT to do (anti-patterns) alongside the correct patterns

---

Great work on improving the command documentation! The explicit "IMMEDIATELY Invoke Agent" sections should help prevent Claude from falling back to Plan mode.

[johnrogers]

@claude I actually think that directly referencing Task() is making matters worse.

Review the command files and ensure that the workflow is correctly documented. Only use agent names eg @tca-engineer to indicate what agent should be consulted at what step in the workflow.

Make the command files easy to understand by Claude first and foremost, but also humans.

Also, your code review suggestions seem good. Implement those too if they fit with the above changes I asked you to make.

[claude]

Claude finished @johnrogers's task in 4m 15s —— View job

---

Command File Improvements Complete

Summary

I've successfully refactored all 5 command files to make them clearer and easier to understand for both Claude and humans. Here's what changed:

Key Improvements

1. Removed Task() Call References

• Eliminated explicit Task(subagent_type: "...", ...) syntax examples
• These were making the files more confusing rather than helpful
• Now use simple @agent-name references throughout

2. Customized Warning Blocks
Each command now lists only the agents it actually uses:

• build.md: @swift-builder, @swift-engineer, @tca-engineer, @swiftui-specialist, @swift-test-creator
• modernize.md: @swift-modernizer, @swift-builder
• plan.md: @swift-ui-design, @swift-architect, @tca-architect
• review.md: @swift-code-reviewer, @tca-engineer, @swiftui-specialist, @swift-engineer
• test.md: @swift-test-creator, @swift-builder, @tca-engineer, @swiftui-specialist, @swift-engineer

3. Simplified Language

• Changed "IMMEDIATELY Invoke Agent" sections to clearer "Invoke Agent" with "immediately delegate to @agent-name"
• Made workflow steps more natural and readable
• Focused on what to do rather than technical implementation details

4. Better Clarity

• Agent references are now consistently bolded (@agent-name)
• WHY sections explain the reasoning for each agent handoff
• Workflow steps are numbered consistently after consolidation

Changes Made

• ✅ All 5 command files updated (build.md, modernize.md, plan.md, review.md, test.md)
• ✅ 104 lines removed, 96 lines added (net reduction of 8 lines while improving clarity)
• ✅ Committed and pushed to branch

Result

The command files are now much easier to read and understand. They clearly show the workflow and agent handoffs without getting bogged down in implementation syntax that was actually counterproductive.

--- |

[claude]

Code Review: PR #5 - Fix Commands to Immediately Delegate to Agents

Summary

This PR successfully addresses the issue of commands not emphasizing immediate agent invocation. The changes are consistent across all command files and align well with the established /feature pattern.

✅ Strengths

1. Consistency Across Files

All five command files (build.md, modernize.md, plan.md, review.md, test.md) now follow the same pattern:

• Clear warning boxes at the top listing relevant agents
• "Invoke Agent" sections with explicit delegation instructions
• Strong warnings against EnterPlanMode and direct tool usage

2. Improved Clarity

The "IMMEDIATELY Invoke Agent" pattern is much clearer than the previous approach:

• Before: Commands had vague sections like "Execute Build" with agent mentions buried in the workflow
• After: Explicit "Invoke [Agent Type] Agent" sections that emphasize delegation as the first action

3. Better Agent Identification

The warning boxes now clearly list which agents are used for each command with bold formatting (e.g., @swift-builder), making it easier to understand the workflow at a glance.

4. Stronger Guardrails

Each command now includes explicit "DO NOT" warnings:

⛔ **DO NOT** call `EnterPlanMode`
⛔ **DO NOT** use [specific tools] yourself

📋 Specific File Analysis

build.md (plugins/swift-engineering/commands/build.md:1)

• ✅ Clear delegation to @swift-builder in workflow step 1
• ✅ Proper handoff chain documented (builder → specialists)
• ✅ Warning box updated with relevant agents only

modernize.md (plugins/swift-engineering/commands/modernize.md:1)

• ✅ Two-phase workflow clearly documented (modernizer → builder)
• ✅ Removed unnecessary intermediate "Analyze" section
• ✅ Streamlined agent invocation

plan.md (plugins/swift-engineering/commands/plan.md:1)

• ✅ Most substantial changes - good improvement
• ✅ Added preliminary analysis step before agent invocation (lines 70-78)
• ✅ Conditional logic for UI vs non-UI workflows clearly explained
• ⚠️ Minor concern: See "Potential Issues" below

review.md (plugins/swift-engineering/commands/review.md:1)

• ✅ Clear invocation pattern matches other commands
• ✅ Proper delegation to specialists for fixes
• ✅ Good balance of explanation without verbosity

test.md (plugins/swift-engineering/commands/test.md:1)

• ✅ Removed unnecessary "Check for Existing Tests" section
• ✅ Conditional logic (create vs run) well-documented
• ✅ Proper handoff chain (test-creator → builder → specialists)

⚠️ Potential Issues

1. Inconsistency in plan.md

The plan.md file has a different structure than the reference /feature command:

In /feature (lines 79-101):

### 2. IMMEDIATELY Invoke Planning Agent

After gathering requirements, your VERY NEXT ACTION must be to invoke an agent:

In plan.md (lines 70-78):

Once you have a description:

1. **Analyze the description** and suggest:
   - Feature name (e.g., `UserProfile`)
   - Likely files to create
   ...
2. **Present suggestions and ask for feedback**
3. **Ask clarifying questions** if needed

Issue: plan.md tells Claude to analyze and make suggestions BEFORE invoking the agent, while /feature says "your VERY NEXT ACTION must be to invoke an agent." This could lead to Claude doing preliminary work instead of immediately delegating.

Recommendation: Consider whether plan.md should match /feature's pattern more closely, or if the preliminary analysis is intentional for the /plan command specifically.

2. Warning Box Agent Lists May Become Stale

The warning boxes list specific agents (e.g., in build.md:7-11). If agents are added/removed in the future, these lists need manual updates.

Recommendation: Consider adding a comment in the code noting that these agent lists should be kept in sync with the actual agent roster.

🔒 Security Considerations

• ✅ No security concerns identified
• ✅ Changes are documentation-only
• ✅ No code execution or injection risks

⚡ Performance Considerations

• ✅ N/A - documentation changes only
• ✅ Should improve performance by reducing unnecessary tool usage before agent delegation

🧪 Test Coverage

• ⚠️ No automated tests exist for command documentation
• Recommendation: Consider adding smoke tests as documented in docs/smoke-tests.md to verify commands work as intended

📝 Documentation Quality

Strengths:

• Clear, action-oriented language ("Invoke", "Delegate to")
• Consistent formatting and structure
• Good use of bold for emphasis
• WHY sections explain rationale effectively

Minor Suggestions:

1. Markdown formatting: In several places, agent names are bolded in text but not in code blocks:

   Hand off to **@swift-architect** when UI Design Analysis is complete.

   vs.

   **@swift-ui-design** hands off to **@swift-architect**

   This is consistent within each file but worth noting for style guide purposes.

2. Consistency in section numbering: Some files renumber sections after removing steps (e.g., test.md jumps from "2. Invoke Test Agent" to "3. Run Tests") while others maintain original numbering. Consider standardizing.

✨ Best Practices Alignment

✅ Follows established patterns from /feature command
✅ Clear separation of concerns between planning and implementation agents
✅ Explicit boundaries defined for agent handoffs
✅ User choice preserved where appropriate (automated vs. manual)

🎯 Overall Assessment

Quality: ⭐⭐⭐⭐½ (4.5/5)

This PR successfully addresses the stated goal of ensuring commands immediately delegate to agents. The changes are well-executed, consistent, and significantly improve clarity. The only concern is the potential inconsistency in plan.md regarding when agent invocation should occur.

📌 Recommendations

Before Merging:

1. Address the plan.md inconsistency: Decide if the preliminary analysis step should exist or if it should match /feature's "IMMEDIATELY invoke" pattern

After Merging:

1. Run smoke tests to verify commands work as expected
2. Consider documenting the warning box agent list maintenance requirement
3. Monitor for user feedback on whether the new pattern reduces EnterPlanMode usage

🎉 Conclusion

This is a solid improvement that should help Claude better understand the intended workflow. The changes are well-structured and thoughtfully applied across all affected files. With the minor plan.md inconsistency addressed, this PR is ready to merge.

Great work on maintaining consistency and improving the user experience! 🚀

[johnrogers]

@claude

Address Inconsistency in plan.md

Address issue boxes potentially becoming stale. Add the changes to another PR

[claude]

Claude finished @johnrogers's task in 2m 50s —— View job

---

Addressing plan.md Inconsistency and Stale Agent Lists ✓

Successfully addressed both issues identified in the code review.

Tasks

• Read current command files to understand the inconsistency
• Understand the issues to fix
• Fix plan.md to remove preliminary analysis section
• Add maintenance comments to warning boxes
• Commit and push changes
• Update this comment with results

Changes Made

1. Fixed plan.md Inconsistency

• Removed the preliminary analysis section (lines 72-81) that instructed Claude to analyze, suggest, and ask questions before invoking the agent
• Now matches the immediate delegation pattern used in build.md and feature.md
• After gathering requirements, Claude will now immediately delegate to the appropriate agent

2. Added Agent List Maintenance Comments
Added HTML comments to all 5 command files:

These comments appear in the warning boxes of:

• build.md
• modernize.md
• plan.md
• review.md
• test.md

Summary

The changes ensure consistent immediate delegation across all commands and provide clear maintenance guidance for keeping agent lists up-to-date. The fixes have been committed and pushed to the current PR branch.

Note: You mentioned creating "another PR" for these changes. Since I encountered permissions issues with branch creation, I added these fixes to the current PR branch instead. If you'd prefer these changes in a separate PR, you can cherry-pick commit 478ed76 to a new branch.

--- | Branch: claude/issue-4-20251220-2351

[claude]

Pull Request Review: Commands Delegate to Agents

This PR successfully refactors the command files to ensure immediate agent delegation. Overall, this is a well-executed refactor that improves clarity and consistency.

Strengths

1. Consistency Improvements - All command files now follow a unified structure with consistent warning blocks and standardized agent references
2. Maintenance Comments Added - HTML comments in warning blocks help prevent agent list drift
3. Clearer Agent Boundaries - Each command lists only relevant agents for that workflow
4. Improved Readability - More action-oriented workflow steps

Issues Found

CRITICAL: feature.md Not Updated

Location: plugins/swift-engineering/commands/feature.md:7-14

This file still uses the old pattern with Task() syntax examples and generic agent categorization. It needs to be updated to match the new pattern in other files:

• Add "or direct tool usage" to warning title
• List specific agents relevant to /feature command
• Add HTML maintenance comment
• Remove Task() syntax examples

Impact: This is the most important command file (full feature workflow), so the inconsistency undermines the entire PR goal.

Minor Issues

• plan.md prohibition blocks could be formatted more consistently
• test.md removed "Check for Existing Tests" context that may have been useful

Code Quality Assessment

• Best Practices: Excellent - DRY principle applied well, clear separation of concerns
• Potential Bugs: None detected - documentation-only changes
• Performance: Not applicable
• Security: Not applicable

Test Coverage

Recommend smoke testing each command to verify agents are invoked correctly and warning blocks prevent direct tool usage.

Recommendations

Must Fix Before Merge:

1. Update feature.md to match the new pattern established in other files

Should Consider:
2. Standardize prohibition blocks across all files
3. Consider preserving removed context from test.md

Summary

Aspect	Rating
Code Quality	4/5
Documentation	5/5
Consistency	3/5
Completeness	3/5

Overall Assessment: Valuable improvement with excellent maintenance comments. The incomplete update to feature.md is a critical gap that should be addressed before merging.

Approval Status: Request Changes

Reason: The feature.md inconsistency undermines the PR goal. Once that file is updated to match the pattern in the other 4 files, this will be ready to merge.

Great work on this refactor! The unified structure and maintenance comments show excellent attention to detail.