gh-duongdev-ccpm/commands/implementation:start.md

description, allowed-tools, argument-hint

description	allowed-tools	argument-hint
Start implementation - fetch task, list agents, assign subtasks, coordinate parallel work	Bash LinearMCP	<linear-issue-id>

Starting Implementation: $1

You are beginning the Implementation Phase for Linear issue $1.

🚨 CRITICAL: Safety Rules

READ FIRST: $CCPM_COMMANDS_DIR/SAFETY_RULES.md

NEVER submit, post, or update anything to Jira, Confluence, BitBucket, or Slack without explicit user confirmation, even in bypass permission mode.

• ✅ Linear operations are permitted (our internal tracking)
• ⛔ External PM systems require user confirmation for write operations

Implementation Workflow

Step 1: Fetch Task Details from Linear

Use Linear MCP to:

1. Get issue details for: $1
2. Read the full description
3. Extract the checklist
4. Understand all requirements

Display the task summary:

📋 Task: [Title]
Project: [Project name]
Status: [Current status]

Checklist Items:
- [ ] Item 1
- [ ] Item 2
...

Step 1.5: Prepare Visual Context for UI/Design Tasks

READ: commands/_shared-image-analysis.md

Detect UI/design subtasks and prepare visual references for pixel-perfect implementation:

// 1. Extract all subtasks from checklist
const subtasks = extractChecklistItems(issue.description)

// 2. Detect UI/design work using keywords
const uiKeywords = /\b(UI|design|mockup|screen|component|layout|interface|visual|frontend|styling|theme)\b/i

const uiTasks = []
for (const [index, subtask] of subtasks.entries()) {
  if (uiKeywords.test(subtask.description)) {
    uiTasks.push({ index, description: subtask.description })
  }
}

// 3. If UI tasks found, detect and prepare images
if (uiTasks.length > 0) {
  console.log(`🎨 Detected ${uiTasks.length} UI/design subtask(s)`)
  
  const images = detectImages(issue)
  if (images.length > 0) {
    console.log(`📎 Found ${images.length} image(s) for visual reference`)
    
    // Map images to relevant subtasks
    const visualContext = {}
    for (const task of uiTasks) {
      // Match images to subtasks by keyword overlap
      const relevantImages = images.filter(img => 
        // Check if image title/description relates to subtask
        task.description.toLowerCase().includes(img.title.toLowerCase().split('.')[0]) ||
        img.title.toLowerCase().includes('mockup') ||
        img.title.toLowerCase().includes('design') ||
        img.title.toLowerCase().includes('wireframe')
      )
      
      if (relevantImages.length > 0) {
        visualContext[task.index] = relevantImages
      } else {
        // If no specific match, use all UI-related images
        visualContext[task.index] = images.filter(img => 
          /(mockup|design|wireframe|ui|screen|interface)/i.test(img.title)
        )
      }
    }
    
    console.log("✅ Visual context prepared for UI tasks")
    // Store visualContext for use in Step 5
  } else {
    console.log("⚠️ No images found - will implement from text descriptions")
  }
}

Why This Matters:

• Pixel-perfect implementation: Frontend/mobile agents see the exact design mockup
• No information loss: Direct visual reference vs. lossy text translation
• Design fidelity: ~95-100% accuracy (vs. ~70-80% from text descriptions)
• Faster implementation: No interpretation needed, implement directly from mockup

Note: Images were preserved in planning phase (Subtask 4) specifically for this step.

Step 1.6: Load Figma Design Context

READ: commands/_shared-figma-detection.md

For UI/design tasks, check if Figma design system was extracted during planning phase:

// 1. Check Linear description for Figma design system section
const hasFigmaContext = issue.description.includes("## 🎨 Design System Analysis")

if (hasFigmaContext && uiTasks.length > 0) {
  console.log("🎨 Figma design system found in planning")

  // 2. Extract design system data from Linear description
  // The design system includes:
  // - Color palette with Tailwind mappings
  // - Typography with font families
  // - Spacing scale with Tailwind utilities
  // - Component library
  // - Layout patterns

  // 3. Also check for cached design data in Linear comments
  const designSystemComment = issue.comments?.find(c =>
    c.body.includes("🎨 Figma Design Context") ||
    c.body.includes("Design System Analysis")
  )

  if (designSystemComment) {
    console.log("  ✓ Design tokens extracted")
    console.log("  ✓ Tailwind class mappings available")
    console.log("  ✓ Component patterns documented")
    console.log("")
    console.log("💡 Frontend agents will receive:")
    console.log("  • Exact color hex codes → Tailwind classes")
    console.log("  • Font family mappings")
    console.log("  • Spacing values → Tailwind scale")
    console.log("  • Layout patterns (flex, grid, auto-layout)")
    console.log("  • Component structure and hierarchy")
  }

  // 4. Store for passing to frontend/mobile agents
  const figmaContext = {
    hasDesignSystem: true,
    designSystemMarkdown: extractFigmaSection(issue.description),
    cacheComment: designSystemComment?.body
  }

  console.log("✅ Figma design context loaded for implementation")
} else if (uiTasks.length > 0) {
  console.log("ℹ️  No Figma design system - using static images only")
}

What agents receive:

• Frontend Developer: Figma design tokens + Tailwind mappings + component structure
• Mobile Developer: Same design system adapted for React Native
• UI Designer: Component library and pattern documentation

Benefits:

• Consistency: Exact color/font/spacing values from design system
• Efficiency: No manual color picking or spacing guessing
• Quality: Design system compliance guaranteed
• Speed: Pre-mapped Tailwind classes ready to use

Fallback: If no Figma context, agents use static images + text descriptions.

💡 Hint: Try the New Natural Command

For a simpler workflow, consider using:

/ccpm:work [issue-id]

Benefits:

• Auto-detects issue from git branch if not provided
• Auto-detects mode (start vs resume)
• Part of the 6-command natural workflow
• See: Quick Start Guide

This command still works perfectly! The hint is just a suggestion.

---

Step 2: List Available Subagents

Read the CLAUDE.md file in the project root to get subagent definitions.

Display available agents:

🤖 Available Subagents:

1. frontend-agent
   - Capabilities: React/Vue, UI/UX, styling
   - Use for: UI components, frontend features

2. backend-agent
   - Capabilities: APIs, database, auth
   - Use for: Server logic, endpoints

3. mobile-agent
   - Capabilities: React Native, iOS/Android
   - Use for: Mobile development

4. integration-agent
   - Capabilities: API integration, third-party services
   - Use for: Connecting systems

5. verification-agent
   - Capabilities: Testing, QA, code review
   - Use for: Final verification

6. devops-agent
   - Capabilities: CI/CD, deployment
   - Use for: Infrastructure tasks

[Add more agents as defined in CLAUDE.md]

Step 3: Create Assignment Plan

For each checklist item, determine:

1. Which agent is best suited for the task
2. Dependencies between subtasks
3. Parallel execution opportunities

Create an assignment map:

📝 Assignment Plan:

✅ Group 1 (Run First):
- [ ] Subtask 1 → database-agent

✅ Group 2 (After Group 1):
- [ ] Subtask 2 → backend-agent

✅ Group 3 (Parallel, after Group 2):
- [ ] Subtask 3 → frontend-agent (parallel)
- [ ] Subtask 4 → mobile-agent (parallel)

✅ Group 4 (After Group 3):
- [ ] Subtask 5 → integration-agent

✅ Group 5 (Final):
- [ ] Subtask 6 → verification-agent

Step 4: Update Linear

READ: commands/_shared-linear-helpers.md

Use Linear MCP to update issue status and labels:

try {
  // Get team ID from issue
  const teamId = issue.team.id;

  // Step 4a: Get valid "In Progress" state ID
  const inProgressStateId = await getValidStateId(teamId, "In Progress");

  // Step 4b: Get or create "implementation" label
  const implementationLabel = await getOrCreateLabel(teamId, "implementation", {
    color: "#26b5ce",
    description: "CCPM: Task in implementation phase"
  });

  // Step 4c: Get current labels and remove "planning" if present
  const currentLabels = issue.labels || [];
  const currentLabelIds = currentLabels.map(l => l.id);

  // Find planning label ID to remove
  const planningLabel = currentLabels.find(l =>
    l.name.toLowerCase() === "planning"
  );

  // Build new label list: remove planning, add implementation
  let newLabelIds = currentLabelIds.filter(id =>
    id !== planningLabel?.id
  );

  // Add implementation label if not already present
  if (!currentLabels.some(l => l.name.toLowerCase() === "implementation")) {
    newLabelIds.push(implementationLabel.id);
  }

  // Step 4d: Update issue with new status and labels
  await mcp__agent-mcp-gateway__execute_tool({
    server: "linear",
    tool: "update_issue",
    args: {
      id: issue.id,
      stateId: inProgressStateId,
      labelIds: newLabelIds
    }
  });

  console.log("✅ Linear issue updated:");
  console.log("   Status: In Progress");
  console.log("   Labels: implementation (planning removed)");

} catch (error) {
  console.error("⚠️ Failed to update Linear issue:", error.message);
  console.warn("⚠️ Continuing with implementation, but status/labels may not be updated.");
  console.log("   You can manually update status in Linear if needed.");
}

Step 4e: Add comment with assignment plan:

const commentBody = `## 🚀 Implementation Started

### Agent Assignments:
${assignmentPlan.map(group =>
  group.subtasks.map(st =>
    `- ${st.description} → ${st.agent}`
  ).join('\n')
).join('\n\n')}

### Execution Strategy:
${assignmentPlan.map((group, idx) =>
  `- Group ${idx + 1}: ${group.parallel ? 'Parallel execution' : 'Sequential execution'}`
).join('\n')}
`;

try {
  await mcp__agent-mcp-gateway__execute_tool({
    server: "linear",
    tool: "create_comment",
    args: {
      issueId: issue.id,
      body: commentBody
    }
  });

  console.log("✅ Implementation plan added to Linear comments");
} catch (error) {
  console.error("⚠️ Failed to add comment:", error.message);
  // Not critical, continue
}

Step 5: Begin Execution

Now you're ready to invoke subagents!

For each subtask:

1. Invoke the assigned agent with full context
2. Provide clear success criteria
3. After completion, use /update command

Execution Guidelines

Invoking Subagents

When invoking a subagent, always provide:

Context:

• Full task description from Linear
• Specific subtask requirements
• Related code files to modify
• Patterns to follow (from CLAUDE.md)

Success Criteria:

• What "done" looks like
• Testing requirements
• Performance/security considerations

Example invocation:

Invoke backend-agent to implement authentication endpoints:

Context:
- Linear issue: $1
- Subtask: "Implement JWT authentication endpoints"
- Files to modify: src/api/auth.ts, src/middleware/auth.ts

Requirements:
- POST /api/auth/login - JWT authentication
- POST /api/auth/logout - Token invalidation
- POST /api/auth/refresh - Token refresh
- Rate limiting: 5 requests/minute
- Follow patterns in src/api/users.ts

Success Criteria:
- All endpoints functional
- Tests pass
- No linting errors
- Security best practices followed

Invoking Frontend/Mobile Agents with Visual References

CRITICAL for UI/Design Tasks: When invoking frontend-developer or mobile-developer agents for UI/design subtasks:

If visual context exists (from Step 1.5):

Invoke frontend-developer to implement [UI component]:

**Design Mockup** (view directly):
- mockup-name.png: https://linear.app/attachments/[url]

Load the mockup using WebFetch:
[Agent will automatically see the image via WebFetch tool]

**Implementation Requirements**:
- Match EXACT layout and spacing from mockup above
- Extract and use exact colors (hex values from mockup)
- Match typography: font sizes, weights, line heights from mockup
- Implement component hierarchy shown in mockup
- Responsive breakpoints visible in mockup

**Available Components** (from codebase):
[List reusable components found during planning]

**Success Criteria**:
- Pixel-perfect match to mockup (~95-100% fidelity)
- All colors extracted from mockup and used correctly
- Spacing and layout matches mockup measurements
- Component structure follows mockup hierarchy
- Works on all target devices shown in mockup

**DO NOT** rely on text descriptions. Implement directly from the visual mockup loaded above.

Example invocation with mockup:

Invoke frontend-developer to implement login screen UI:

Context:
- Linear issue: WORK-123
- Subtask: "Implement login screen UI component"
- Files to create/modify: src/components/Auth/LoginScreen.tsx

**Design Mockup** (view directly):
- login-mockup.png: https://linear.app/attachments/abc123/login-mockup.png

Use WebFetch to load and view the mockup above. Implement the login screen to match the mockup exactly.

Implementation Requirements:
- Extract exact colors from mockup (primary blue, backgrounds, text colors)
- Match spacing and padding shown in mockup
- Implement form layout as shown (centered card, input fields, button)
- Typography: Match font sizes and weights from mockup
- Use available components: Card, Input, Button, Link

Success Criteria:
- Pixel-perfect implementation matching mockup
- All interactive elements functional
- Responsive design matches mockup behavior
- Accessibility: proper labels, keyboard navigation
- Tests pass for all functionality

DO NOT interpret or guess the design. Implement directly from the visual mockup above.

Benefits of Direct Visual Reference:

• Eliminates translation loss: No text interpretation needed
• Exact design fidelity: ~95-100% accuracy vs. ~70-80% from text
• Faster implementation: No back-and-forth clarifications
• Pixel-perfect results: Agents measure directly from mockup
• Color accuracy: Extract exact hex values from image
• Layout precision: Measure spacing and dimensions from mockup

Fallback: If no mockups available, proceed with text description as before.

Parallel Execution

For subtasks that can run in parallel:

1. Invoke all agents simultaneously
2. Each works independently
3. Wait for all to complete before moving to next group

Status Updates

After EACH subtask completion:

/update $1 <subtask-index> completed "<summary of what was done>"

Next Steps

After displaying the assignment plan:

1. Start with Group 1 - Invoke first agent(s)
2. Update after each subtask - Use /update command
3. Move through groups sequentially (except parallel groups)
4. After all subtasks done - Run /check $1

Output Format

✅ Implementation Started!

📋 Task: [Title]
🔗 Linear: https://linear.app/workspace/issue/$1

🤖 Agent Assignments Created
📝 Execution plan in Linear comments

⚡ Ready to Execute!

Next: Invoking [first-agent] for Subtask 1...
[Then actually invoke the agent]

Remember

• Provide full context to each subagent
• Update Linear after each subtask
• Execute parallel tasks simultaneously when possible
• Follow patterns defined in CLAUDE.md
• Run quality checks before verification

Step 1.6: Load Figma Design Context

READ: commands/_shared-figma-detection.md

If Figma links were detected during planning, load them for implementation:

# Check if Figma context exists from planning phase
FIGMA_CONTEXT_FILE="/tmp/figma-context-${1}.json"

if [ -f "$FIGMA_CONTEXT_FILE" ]; then
  FIGMA_LINKS=$(cat "$FIGMA_CONTEXT_FILE")
  FIGMA_COUNT=$(echo "$FIGMA_LINKS" | jq 'length')
  
  if [ "$FIGMA_COUNT" -gt 0 ]; then
    echo "🎨 Loaded $FIGMA_COUNT Figma design(s) from planning phase"
    
    # Display Figma context
    echo "$FIGMA_LINKS" | jq -r '.[] | "  - \(.file_name): \(.canonical_url)"'
    
    # Store for agent context
    FIGMA_AVAILABLE=true
  fi
else
  # Try to detect from Linear issue directly
  echo "ℹ️  No cached Figma context - checking Linear issue..."
  LINEAR_DESC=$(linear_get_issue "$1" | jq -r '.description')
  FIGMA_LINKS=$(./scripts/figma-utils.sh extract-markdown "$LINEAR_DESC")
  FIGMA_COUNT=$(echo "$FIGMA_LINKS" | jq 'length')
  
  if [ "$FIGMA_COUNT" -gt 0 ]; then
    echo "✅ Detected $FIGMA_COUNT Figma link(s) from Linear"
    FIGMA_AVAILABLE=true
  else
    echo "ℹ️  No Figma designs found"
    FIGMA_AVAILABLE=false
  fi
fi

Map Figma Designs to UI Subtasks

For UI/design subtasks identified in Step 1.5, map relevant Figma links:

if (figmaAvailable && uiTasks.length > 0) {
  console.log("🎨 Mapping Figma designs to UI subtasks...")
  
  const figmaContext = {}
  for (const task of uiTasks) {
    // Match Figma designs to subtasks by keyword overlap
    const relevantDesigns = figmaLinks.filter(design => 
      task.description.toLowerCase().includes(design.file_name.toLowerCase()) ||
      design.file_name.toLowerCase().includes('ui') ||
      design.file_name.toLowerCase().includes('design') ||
      design.file_name.toLowerCase().includes('mockup')
    )
    
    if (relevantDesigns.length > 0) {
      figmaContext[task.index] = relevantDesigns
      console.log(`  ✅ Subtask ${task.index + 1}: ${relevantDesigns.length} Figma design(s)`)
    } else {
      // Use all Figma links as fallback
      figmaContext[task.index] = figmaLinks
      console.log(`  ℹ️ Subtask ${task.index + 1}: Using all Figma designs`)
    }
  }
  
  console.log("✅ Figma context mapped for pixel-perfect implementation")
  // Store figmaContext for use in Step 5 (agent invocation)
}

Agent Context Enhancement

When invoking frontend/mobile agents for UI tasks:

// In Step 5: Assign Subtasks to Agents
if (subtask.hasVisualContext) {
  const images = visualContext[subtask.index] || []
  const figma = figmaContext[subtask.index] || []
  
  agentPrompt += `

**Visual References**:
- Images: ${images.length} screenshot(s)/mockup(s) attached
${images.map((img, i) => `  ${i+1}. ${img.title}: ${img.url}`).join('\n')}

- Figma Designs: ${figma.length} live design(s) available
${figma.map((design, i) => `  ${i+1}. ${design.file_name}: ${design.canonical_url}`).join('\n')}

**Implementation Priority**:
1. Use Figma as authoritative design source (live, up-to-date)
2. Use images for quick visual reference
3. Implement pixel-perfect from Figma specifications
`
}

Why This Matters:

• Authoritative Source: Figma is the live design specification
• Always Current: Unlike static images, Figma shows latest design iterations
• Precise Specifications: Access to exact measurements, colors, spacing
• Component Mapping: Direct reference for component implementation
• Design Fidelity: ~98-100% accuracy (vs. ~95% from images, ~70% from text)

Performance: Loading Figma context adds <100ms (file read). Phase 2 will enable on-demand MCP extraction (~1-3s per design).

Error Handling: If Figma links unavailable, fall back to images → text descriptions (graceful degradation).