update specify step to be multi-agent

[MichaelClifford]

No description provided.

[jeremyeder]

How does the output look before and after?

[github-actions]

Code Review - Multi-Agent Specification Workflow

Summary

This PR enhances the RFE specify phase with a structured multi-agent collaborative workflow. The change replaces a simple single-line prompt with a comprehensive 5-step process involving multiple agents.

---

Strengths

✅ Well-structured workflow: Clear 5-step process with defined responsibilities
✅ Agent selection logic: Smart mapping of feature types to appropriate agent pairs
✅ Document versioning: Proper artifact management with version tracking
✅ Parallel execution: Correctly instructs to use parallel Task tool calls for agent reviews
✅ Good instructions: Detailed guidance for each step with specific deliverables

---

Issues & Recommendations

1. Component Size Violation ⚠️

Issue: This file is growing large with complex logic. The new prompt adds 56 lines to an already substantial component.

Recommendation: Extract prompt templates into a separate module:

// src/lib/rfe-prompts.ts
export const MULTI_AGENT_SPECIFY_PROMPT = (description: string) => `
MULTI-AGENT COLLABORATIVE SPECIFICATION WORKFLOW:
...
`;

// Then in component:
const basePrompt = isSpecify
  ? MULTI_AGENT_SPECIFY_PROMPT(workflow.description)
  : `/speckit.${phase}`;

Benefit: Improves testability, maintainability, and follows separation of concerns.

---

2. Missing TypeScript Types

Issue: The prompt references agents (Parker, Archie, Stella, etc.) but there's no type safety ensuring these agents exist.

Recommendation: Add agent validation:

// Validate agents exist in AVAILABLE_AGENTS
const SPECIFY_AGENTS = ['Parker', 'Archie', 'Stella', 'Felix', 'Taylor', 'Terry', 'Casey', 'Neil'] as const;
type SpecifyAgent = typeof SPECIFY_AGENTS[number];

---

3. Hardcoded Directory Path ⚠️

Issue: The prompt hardcodes specs/[feature-dir]/ without validation that this directory structure exists or is appropriate for the project.

Recommendation:

• Either make the specs directory path configurable via environment variables
• Or validate/create the directory structure in the backend before starting the session
• Consider using the existing workflowWorkspace prop instead of hardcoding paths

---

4. Error Handling Gap

Issue: The prompt workflow has multiple steps but no guidance on what to do if:

• Parker fails to create the outline
• Agent selection fails
• Parallel agent launches fail
• Document saving fails

Recommendation: Add a failure handling section to the prompt:

## Error Handling:
- If Parker fails, retry once then fall back to simplified outline
- If agent selection fails, default to Stella + Archie
- If document saving fails, continue but note the failure

---

5. User Experience Concern

Issue: This workflow is significantly more complex and will take much longer to execute than the previous single-step approach. Users may not understand why "Start Chat" takes so long.

Recommendations:

1. Add a tooltip/help text explaining this phase uses a multi-agent workflow
2. Consider adding progress indicators if possible (though may require backend changes)
3. Document expected execution time in user docs

---

6. Testing Gap 🚨

Issue: No tests for this critical workflow change. The prompt logic is complex and prone to errors.

Required: Add tests for:

describe('RfePhaseCards - Specify Phase', () => {
  it('should generate multi-agent prompt for specify phase', () => {
    const prompt = getSpecifyPrompt('Feature X');
    expect(prompt).toContain('MULTI-AGENT COLLABORATIVE');
    expect(prompt).toContain('Parker (Product Manager)');
  });

  it('should use standard prompt for non-specify phases', () => {
    const prompt = getPromptForPhase('plan');
    expect(prompt).toBe('/speckit.plan');
  });
});

---

7. Prompt Quality Issues

a) Inconsistent naming: [feature-dir] is a placeholder but not defined

• Fix: Use dynamic path based on workflow properties

b) Missing validation: No check if workflow.description is empty

• Fix: Add fallback for empty descriptions

c) Typo risk: Manual agent names could have typos ("Archie" vs "archie")

• Fix: Reference from AVAILABLE_AGENTS constant

---

Security Considerations

✅ No security issues detected: The prompt construction uses template literals safely, no XSS risk since it's used server-side in K8s job.

---

Performance Considerations

⚠️ Multi-agent execution will be slower:

• Previous: ~1-2 minutes for single specify run
• New: Estimated 5-10 minutes (Parker outline + 2 parallel agents + Parker revision + final specify)

Recommendation: Consider adding a "Quick Specify" option that uses the old single-step approach for simple features.

---

Code Quality (Per DESIGN_GUIDELINES.md)

✅ Uses Shadcn Button component
✅ Proper loading states with Loader2
✅ No any types
✅ Uses React Query via useCreateSession
❌ Component over 200 lines (needs refactoring)
❌ Missing tests

---

Final Verdict

Status: ⚠️ Needs Work before merge

Must Fix:

1. Extract prompt templates to separate module
2. Add tests for prompt generation logic
3. Define/validate [feature-dir] path
4. Add error handling guidance in prompt

Should Fix:
5. Add agent name type safety
6. Add user-facing documentation about longer execution time
7. Consider configurable specs directory path

Nice to Have:
8. Add "Quick Specify" option for simple features
9. Add progress indicators for multi-step workflow

---

Questions for Author

1. Have you tested this workflow end-to-end with actual agent execution?
2. What's the expected execution time for the full workflow?
3. Should the specs directory structure be configurable per project?
4. Do we need backward compatibility with the old single-step approach?

---

Overall Assessment: Good architectural direction with structured multi-agent collaboration, but needs refactoring for maintainability and testing before merge.

[github-actions]

Code Review - Multi-Agent Specification Workflow

Summary: This PR enhances the RFE workflow to use a structured multi-agent collaborative approach for the specify phase. The change replaces a simple single-line prompt with a comprehensive 56-line workflow guide.

---

Strengths:

• Clear 5-step workflow structure
• Smart agent pairing based on feature type
• Document versioning for audit trail
• Parallel execution instructions
• Integration with existing /specify command

---

Issues and Recommendations:

1. Component Size Violation (CRITICAL)

   • File is now 447 lines, exceeding the 200-line limit in DESIGN_GUIDELINES.md
   • Impact: Harder to maintain, test, and review
   • Solution: Break down into smaller components (phase-card.tsx, phase-actions.tsx, workflow-prompts.ts)

2. Hardcoded Prompt Template

   • The 56-line prompt is embedded directly in JSX
   • Makes it hard to test independently and not reusable
   • Recommendation: Extract to separate module for maintainability

3. Missing Type Safety for Agent Selection

   • Agent names and roles are hardcoded strings
   • Risk: Changes to AVAILABLE_AGENTS won't be validated
   • Recommendation: Use type-safe references from agents module

4. No Validation for Feature Directory Path

   • Prompt references specs/[feature-dir]/ without validation
   • Recommendation: Add validation or make path explicit

5. Consider Interactive vs Batch Mode

   • Question: Should specify phase use interactive mode for complex multi-agent workflow?
   • Current batch mode assumes all steps execute autonomously

6. Testing Strategy

   • Missing: No tests for new prompt logic
   • Recommendation: Add unit tests for prompt generation

---

Pre-Commit Checklist Status:

• ❌ Components under 200 lines (447 lines)
• ✅ All data operations use React Query
• ✅ All buttons have loading states
• ✅ Proper TypeScript types (no any)
• ⚠️ Could benefit from extracted constants/modules
• ⚠️ Missing tests for new prompt logic

---

Recommendations Priority:

1. HIGH: Extract prompt template to separate module
2. HIGH: Break component into smaller files
3. MEDIUM: Add type-safe agent selection constants
4. MEDIUM: Add unit tests for prompt generation
5. LOW: Document batch vs interactive mode decision

---

Questions for Author:

1. Have you tested this with actual multi-agent sessions? What was the output quality?
2. Should specify phase support interactive mode for this complex workflow?
3. Are the agent selection criteria documented somewhere?
4. How long does a typical multi-agent specify phase take to complete?

---

Approval: Conditional approval with follow-up refactoring needed.

• Logic and workflow design are sound
• Extract prompt template before merge
• Create follow-up issue for component breakdown
• Document the new workflow behavior in user docs

[MichaelClifford]

@jeremyeder You can see the comparison between the two outputs here:

Original Prompt:
https://github.com/MichaelClifford/vteam-rfes/blob/ambient-default-specify-prompt/specs/001-add-dark-mode/spec.md

Multi-Agent Prompt:
https://github.com/MichaelClifford/vteam-rfes/blob/ambient-multi-agent-specify/specs/001-dark-mode-feature/spec.md

Quick Summary, the Multi-Agent Prompt appears to produce a more complete spec.md

[github-actions]

PR Review: Update Specify Step to Multi-Agent

Summary

This PR updates the "specify" phase of the RFE workflow to implement a multi-agent collaborative specification process. The change replaces a simple slash command with a comprehensive multi-step workflow involving Product Manager (Parker), Architect (Archie), and other specialized agents.

---

Code Quality & Best Practices

✅ Strengths

1. Follows Frontend Design Guidelines

   • Uses Shadcn UI components (Button, Badge, Card) ✓
   • Proper TypeScript typing throughout ✓
   • Uses React Query patterns (useCreateSession) ✓
   • Component colocation is correct ✓

2. Clear Workflow Structure

   • Well-defined 5-step process with clear responsibilities
   • Good separation of concerns (PM creates outline, agents review, PM refines)
   • Explicit agent selection criteria based on feature type

3. Strong Citation Requirements

   • Excellent emphasis on evidence-based claims with actual sources
   • Clear examples of correct vs incorrect citations
   • Multiple reminders to include citations section in agent prompts

---

Issues & Concerns

🔴 Critical Issues

1. Prompt String Length (96+ Lines)

The new basePrompt for the specify phase is 96 lines long (lines 304-399), embedded directly in JSX. This violates best practices:

Problems:

• Makes the component harder to read and maintain
• Mixing business logic (workflow instructions) with UI code
• Difficult to version control prompt changes separately
• No ability to reuse or test prompts independently

Recommendation:
Extract prompts to a separate module (e.g., src/lib/rfe-prompts.ts)

2. Template String Escaping Issues

Lines 385-394 use backticks inside template literals, requiring escaping and creating error-prone code. Consider using single quotes or extracting to a constant.

3. Missing User Feedback for Multi-Agent Workflow

The specify phase now involves a complex multi-step process (5 steps with multiple agent invocations), but the UI still shows the same generic "Starting…" and "Generate" button labels. Users have no visibility into:

• Which step the workflow is on
• Which agents are being invoked
• How long the process might take

Recommendation:
Add a progress indicator or status messages for multi-agent workflows.

⚠️ Medium Priority Issues

4. Citation Requirements Duplication

The citation requirements section appears 3 times in the prompt (lines 308-340, 346, 373). This:

• Increases prompt token usage unnecessarily
• Makes maintenance harder (3 places to update if requirements change)
• Creates risk of inconsistency

Recommendation:
Structure the prompt to define citation requirements once at the top, then reference them.

5. Hardcoded Agent Selection Logic

Lines 360-367 hardcode agent selection criteria in the prompt. Changes to agent roles require code changes, and this is not configurable per project/workflow.

Recommendation:
Consider moving agent selection logic to backend/configuration or at minimum extract to a shared constant.

6. No Validation for Multi-Agent Prerequisites

The specify phase now requires access to Parker (PM agent) and 2+ review agents. Missing checks:

• Are these agents available in the current environment?
• Does the user have permissions to invoke multiple agents?
• What happens if agent invocation fails midway?

---

Performance Considerations

Token Usage

The new prompt is ~500+ tokens compared to the previous ~20 tokens (/speckit.specify). For workflows with many phases or frequent re-runs, this could:

• Increase API costs significantly
• Slow down session creation (larger payloads)
• Hit token limits faster in the session itself

Recommendation:

• Consider prompt compression techniques
• Move static instructions to system prompts or documentation links
• Use slash command expansion on the backend side

---

Security Concerns

✅ No Major Security Issues Detected

The changes do not introduce security vulnerabilities:

• No user input is directly interpolated unsafely
• No new API calls or authentication changes
• Uses existing createSessionMutation patterns

Minor note: The workflow.description is interpolated into the prompt (line 344). Ensure this is sanitized on the backend when the workflow is created.

---

Test Coverage

⚠️ Missing Tests

This PR modifies critical workflow logic but does not include:

• Unit tests for the new multi-agent workflow
• Integration tests to verify agent invocation sequence
• Tests for prompt generation logic

Recommendation:
Add tests for:

1. Prompt generation for different workflow types
2. Agent selection logic (if moved to separate function)
3. UI behavior when specify phase is triggered

---

Suggestions for Improvement

1. Progressive Enhancement

Consider making the multi-agent workflow optional via feature flag. This allows gradual rollout, A/B testing, and fallback if multi-agent workflow has issues.

2. Document Versioning Path

Lines 384-388 specify file paths like specs/[feature-dir]/outline-v1-pm-initial.md. Clarify:

• Is [feature-dir] a placeholder or literal?
• How is the feature directory determined?
• What if the directory does not exist?

3. Error Handling for Agent Failures

The workflow assumes all agent invocations succeed. Consider adding guidance for what to do if Parker fails, if review agents are not available, or retry/recovery strategies.

---

Frontend Standards Compliance

Based on DESIGN_GUIDELINES.md:

Standard	Status	Notes
Zero any types	✅ Pass	No any types detected
Shadcn components	✅ Pass	Uses Button, Badge, Card correctly
React Query	✅ Pass	Uses useCreateSession mutation
Type over interface	✅ Pass	Uses type (RfePhaseCardsProps)
Component size	✅ Pass	542 lines but acceptable for complex UI
Button loading states	✅ Pass	Shows Loader2 during mutation
Colocated components	✅ Pass	Correctly located in RFE page directory

---

Recommendations Summary

Must Address Before Merge:

1. ❌ Extract prompt to separate module - Critical for maintainability
2. ❌ Deduplicate citation requirements - Appears 3x in prompt
3. ⚠️ Add tests for new workflow logic

Should Address Soon:

4. ⚠️ Add user feedback/progress indication for multi-step workflow
5. ⚠️ Validate agent availability before starting workflow
6. ⚠️ Document file path resolution for versioned documents

Nice to Have:

7. 💡 Feature flag for progressive rollout
8. 💡 Error handling guidance in prompt
9. 💡 Token usage optimization

---

Overall Assessment

Code Quality: ⭐⭐⭐⭐ (4/5)

• Well-structured workflow design
• Follows frontend standards
• Good attention to citation requirements

Risk Level: 🟡 Medium

• Large prompt changes could affect user experience
• No tests for critical workflow logic
• Missing validation for prerequisites

Recommendation: Request Changes

The multi-agent approach is a significant improvement for specification quality, but the implementation needs refinement:

1. Extract and deduplicate prompt logic
2. Add tests
3. Consider user experience implications of longer workflows

Once these issues are addressed, this will be a strong addition to the platform! 🚀

[github-actions]

Code Review: Multi-Agent Collaborative Specification Workflow

CRITICAL ISSUES (BLOCKER):

1. Component Size Violation - rfe-phase-cards.tsx is 548 lines, violating the 200-line guideline

   • Fix: Extract the 102-line prompt (lines 304-405) to src/lib/rfe-prompts.ts
   • This will improve testability and maintainability

2. Long String Literal - The massive inline prompt should be extracted to a separate file

3. Missing Error Handling - No specific error messaging for /specify command failures

4. Template String Escaping - Backticks in code examples may not be properly escaped

MEDIUM PRIORITY:

5. No TypeScript Type Safety - Agent names are hardcoded, should use AVAILABLE_AGENTS constant
6. Missing Test Coverage - No tests for prompt generation or citation requirements

STRENGTHS:

• Well-structured 5-step multi-agent workflow
• Excellent citation requirements with clear examples
• Document versioning preserves specification evolution
• Mandatory spec generation prevents incomplete workflows

RECOMMENDATION: REQUEST CHANGES

The concept is excellent (5 stars), but implementation needs refactoring (3 stars). Please extract the prompt to a separate file to comply with component size guidelines before merging.

Great work on the workflow design!

[github-actions]

Code Review: Multi-Agent Specify Workflow

Thank you for this enhancement! This PR introduces a structured multi-agent collaborative workflow for the specify phase.

✅ Strengths

1. Well-Structured Workflow: The 5-step process (PM outline → agent selection → parallel reviews → versioning → final spec) is clear and logical.

2. Citation Requirements: Excellent addition of strict citation requirements with actual links. This will significantly improve specification quality and prevent unverified claims.

3. Agent Specialization: The feature-type-based agent selection criteria is smart and leverages domain expertise effectively.

4. Document Versioning: Explicit versioning provides excellent audit trail.

5. Clear Examples: The CORRECT vs INCORRECT citation examples are very helpful.

🔍 Critical Issues

Command Inconsistency (Lines 393, 396)

The prompt references /speckit.specify in Step 5, but the actual command structure appears to be /specify based on the context. Use consistent command naming throughout.

Component Size Violation

This component is now 547 lines, significantly exceeding the 200-line limit specified in DESIGN_GUIDELINES.md. Extract the specify workflow prompt into a separate utility file for better maintainability.

⚠️ Potential Issues

1. Template Literal Escaping: Backticks in file paths (lines 385, 393) may need verification
2. Error Handling: No handling for agent unavailability or command failures
3. Hardcoded Assumptions: Assumes directory structures exist without validation

🎯 Recommendations

1. Add validation for Parker agent availability before starting workflow
2. Extract prompt to src/lib/rfe-workflow-prompts.ts
3. Add workflow metadata tracking in session annotations
4. Consider citation validation step before finalizing spec.md

🧪 Testing Needed

• Test full workflow end-to-end with sample RFE
• Verify template literal escaping doesn't break prompts
• Test error scenarios (agent unavailable, command failures)
• Verify all versioned documents are created correctly

📋 Pre-Merge Checklist

• Fix command inconsistency
• Extract prompt to utility file
• Test template literal escaping
• Add error handling
• Run npm run build with 0 errors/warnings

🎉 Conclusion

Valuable enhancement! Main issues: command inconsistency (critical) and component size (important). Recommend addressing these before merging.

Great work on improving specification quality! 🚀

[github-actions]

Code Review: Multi-Agent Specification Workflow

This PR enhances the RFE "specify" phase with a structured multi-agent collaborative workflow. It replaces a simple slash command with an elaborate multi-step process involving Parker (PM), two domain experts, document versioning, and final spec generation.

---

✅ Strengths

1. Well-Structured Workflow: Clear progression through PM outline → agent selection → parallel reviews → versioning → final spec
2. Citation Requirements: Excellent section mandating actual links, preventing fabricated sources
3. Smart Agent Selection: Feature-type based selection (Infrastructure→Archie+Stella, UI→Felix+Stella, etc.)
4. Document Versioning: Saves intermediate artifacts for audit trail and transparency
5. Clear Terminal Condition: Explicitly requires spec.md generation

---

⚠️ Critical Issues (P0 - Block merge)

1. Frontend Code Quality Violations

Problem: 103-line workflow prompt hardcoded in UI component (rfe-phase-cards.tsx:303-405)

• Violates separation of concerns (business logic in presentation)
• File now 548 lines (exceeds 200-line guideline)
• Difficult to maintain and test

Fix: Extract to separate module

// Create: src/lib/workflows/specify-workflow.ts
export function getMultiAgentSpecifyPrompt(requirements: string): string {
  const sanitized = requirements.replace(/`/g, "'").replace(/\$/g, '\\$');
  return `MULTI-AGENT COLLABORATIVE SPECIFICATION WORKFLOW: ... ${sanitized} ...`;
}

// In component:
import { getMultiAgentSpecifyPrompt } from '@/lib/workflows/specify-workflow';
const basePrompt = isSpecify ? getMultiAgentSpecifyPrompt(workflow.description || '') : `/speckit.${phase}`;

2. Security: Prompt Injection Risk

Problem: Line 344 directly interpolates user-controlled workflow.description without sanitization

• If contains backticks or special chars, could break prompt or inject malicious instructions

Fix: Sanitize input before interpolation (see code above)

3. Error Handling Gaps

Problem: Generic "Failed to start session" message (line 463) doesn't indicate which step failed

• Parker outline creation?
• Review agent crash?
• Final /speckit.specify failure?

Fix: Add step-specific error messages

---

⚠️ High Priority Issues (P1)

4. User Experience

• No progress indication: Multi-agent workflow takes time, but users see no step progress
• No immediate session link: Users wait without visibility into running session

5. Component Size

• 548 lines: Should break into PhaseCard.tsx, PhaseActions.tsx, and container

6. Testing

• Zero tests for complex workflow logic
• Should test: citation enforcement, agent selection, error scenarios, versioning paths

7. Documentation

• No user guidance on why specify takes longer or how to interpret intermediate files
• No code comments explaining workflow design decisions

---

📊 Other Concerns

Performance:

• No useMemo - 103-line prompt recreated every render
• Multiple agent invocations = high token usage (no monitoring/limiting visible)
• No timeout handling if agents get stuck

Configurability:

• Hardcoded workflow with no way to adjust citation strictness, agent count, or skip versioning

Input Validation:

• Assumes rfe.md exists or workflow.description is valid

---

🎯 Action Items

Before Merge (P0):

1. Extract prompt to src/lib/workflows/specify-workflow.ts (15 min)
2. Add input sanitization for workflow.description (5 min)
3. Improve error messages with step context (10 min)

Post-Merge (P1):
4. Break component into smaller files
5. Add unit tests for workflow logic
6. Add progress indicators for multi-agent operations
7. Add user documentation/tooltips

---

🎉 Summary

Great concept with systematic, evidence-based spec creation. The multi-agent approach and citation requirements are valuable innovations.

However: Implementation needs refinement for code quality, security, and UX.

Recommendation: ⚠️ Request changes - Address 3 P0 items above before merge. They're quick fixes (30 min total) that significantly improve code quality and security.

[MichaelClifford]

Closing. No longer needed after recent frontend redesign.