gh-duongdev-ccpm/commands/verify.md

description, allowed-tools, argument-hint

description	allowed-tools	argument-hint
Smart verification command - run quality checks and final verification	Bash Task AskUserQuestion	[issue-id]

/ccpm:verify - Smart Verification

Token Budget: ~2,800 tokens (vs ~8,000 baseline) | 65% reduction

Intelligent verification command that runs quality checks followed by final verification in sequence.

Usage

# Auto-detect issue from git branch
/ccpm:verify

# Explicit issue ID
/ccpm:verify PSN-29

# Examples
/ccpm:verify PROJ-123     # Verify PROJ-123
/ccpm:verify              # Auto-detect from branch name "feature/PSN-29-add-auth"

Implementation

Step 1: Parse Arguments & Detect Context

// Parse issue ID from arguments or git branch
let issueId = args[0];

if (!issueId || !/^[A-Z]+-\d+$/.test(issueId)) {
  // Attempt to extract from git branch name
  const branch = await Bash('git rev-parse --abbrev-ref HEAD');
  const match = branch.match(/([A-Z]+-\d+)/);

  if (!match) {
    return error(`
❌ Could not detect issue ID from branch name

Current branch: ${branch}

Usage: /ccpm:verify [ISSUE-ID]

Examples:
  /ccpm:verify PSN-29
  /ccpm:verify              # Auto-detect from branch
    `);
  }

  issueId = match[1];
  console.log(`📌 Detected issue from branch: ${issueId}\n`);
}

Step 2: Fetch Issue via Linear Subagent

Use the Task tool to fetch the issue from Linear:

Invoke the ccpm:linear-operations subagent:

• Tool: Task
• Subagent: ccpm:linear-operations
• Prompt:

  operation: get_issue
  params:
    issueId: "{issue ID from step 1}"
  context:
    cache: true
    command: "verify"
  

Store response as issue object containing:

• issue.id, issue.identifier, issue.title
• issue.description (with checklist)
• issue.state.name, issue.state.id
• issue.labels, issue.team.id

Error handling:

if (subagentResponse.error) {
  console.log(`❌ Error fetching issue: ${subagentResponse.error.message}`);
  console.log('\nSuggestions:');
  subagentResponse.error.suggestions.forEach(s => console.log(`  - ${s}`));
  return;
}

const issue = subagentResponse.issue;

Step 3: Display Verification Flow

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔍 Smart Verify Command
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 Issue: ${issueId} - ${issue.title}
📊 Status: ${issue.state.name}

Verification Flow:
──────────────────
1. Quality Checks (linting, tests, build)
2. Final Verification (code review, security)

Starting verification...

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Step 4: Check Implementation Checklist

Parse checklist from issue description:

const description = issue.description || '';

// Extract checklist items
const checklistItems = description.match(/- \[([ x])\] .+/g) || [];
const totalItems = checklistItems.length;
const completedItems = checklistItems.filter(item => item.includes('[x]')).length;
const progress = totalItems > 0 ? Math.round((completedItems / totalItems) * 100) : 100;

console.log(`📋 Checklist: ${progress}% (${completedItems}/${totalItems} items)\n`);

If checklist incomplete (< 100%), prompt user:

if (progress < 100) {
  const incompleteItems = checklistItems.filter(item => item.includes('[ ]'));

  console.log('⚠️  Checklist incomplete!\n');
  console.log('Remaining items:');
  incompleteItems.forEach(item => {
    console.log(`  ${item.replace('- [ ] ', '⏳ ')}`);
  });
  console.log('');

  // Ask user what to do
  const response = await AskUserQuestion({
    questions: [{
      question: `Checklist is ${progress}% complete. What would you like to do?`,
      header: "Checklist",
      multiSelect: false,
      options: [
        {
          label: "Continue anyway",
          description: "Run checks despite incomplete checklist (warning will be logged)"
        },
        {
          label: "Update checklist",
          description: "Mark completed items first, then continue"
        },
        {
          label: "Cancel",
          description: "Go back and complete remaining items"
        }
      ]
    }]
  });

  if (response.answers[0] === "Cancel") {
    console.log('\n📝 Complete remaining checklist items, then run /ccpm:verify again\n');
    return;
  }

  if (response.answers[0] === "Update checklist") {
    // Interactive checklist update
    const updateResponse = await AskUserQuestion({
      questions: [{
        question: "Which items have you completed?",
        header: "Completed",
        multiSelect: true,
        options: incompleteItems.map((item, idx) => ({
          label: item.replace('- [ ] ', ''),
          description: `Mark item ${idx + 1} as complete`
        }))
      }]
    });

    // Update checklist in description using linear-operations subagent
    if (updateResponse.answers && updateResponse.answers.length > 0) {
      const selectedIndices = updateResponse.answers.map(answer => {
        // Extract index from the label (assuming format "Item text")
        const itemIndex = incompleteItems.findIndex(item =>
          item.replace('- [ ] ', '') === answer
        );
        return itemIndex;
      }).filter(idx => idx >= 0);

      if (selectedIndices.length > 0) {
        // Use Task tool to update checklist via subagent
        await Task('linear-operations', `
operation: update_checklist_items
params:
  issue_id: ${issueId}
  indices: [${selectedIndices.join(', ')}]
  mark_complete: true
  add_comment: true
  update_timestamp: true
context:
  command: "verify"
  purpose: "Updating checklist items during verification"
`);

        console.log(`\n✅ Updated ${selectedIndices.length} checklist item(s)\n`);
      }
    }
  }

  if (response.answers[0] === "Continue anyway") {
    console.log('⚠️  Continuing with incomplete checklist\n');
  }
}

Step 5: Run Quality Checks

═══════════════════════════════════════
Step 1/2: Running Quality Checks
═══════════════════════════════════════

A) Detect project type and commands:

const fs = require('fs');
const hasPackageJson = fs.existsSync('./package.json');
const hasPyProject = fs.existsSync('./pyproject.toml');

let lintCommand, testCommand, buildCommand;

if (hasPackageJson) {
  const pkg = JSON.parse(fs.readFileSync('./package.json', 'utf8'));
  lintCommand = pkg.scripts?.lint ? 'npm run lint' : null;
  testCommand = pkg.scripts?.test ? 'npm test' : null;
  buildCommand = pkg.scripts?.build ? 'npm run build' : null;
} else if (hasPyProject) {
  lintCommand = 'ruff check . || flake8 .';
  testCommand = 'pytest';
  buildCommand = null;
}

B) Run checks sequentially:

# Linting
echo "🔍 Running linting..."
${lintCommand}
LINT_EXIT=$?

# Tests
echo "🧪 Running tests..."
${testCommand}
TEST_EXIT=$?

# Build (optional)
if [ -n "${buildCommand}" ]; then
  echo "🏗️  Running build..."
  ${buildCommand}
  BUILD_EXIT=$?
fi

C) Evaluate results:

const results = {
  lint: LINT_EXIT === 0,
  test: TEST_EXIT === 0,
  build: buildCommand ? BUILD_EXIT === 0 : true
};

const allPassed = results.lint && results.test && results.build;

// Display results
console.log('\n📊 Quality Check Results:');
console.log(`  ${results.lint ? '✅' : '❌'} Linting`);
console.log(`  ${results.test ? '✅' : '❌'} Tests`);
if (buildCommand) {
  console.log(`  ${results.build ? '✅' : '❌'} Build`);
}
console.log('');

D) Handle failure:

if (!allPassed) {
  console.log('❌ Quality Checks Failed\n');
  console.log('To debug and fix issues:');
  console.log(`  /ccpm:verification:fix ${issueId}\n`);
  console.log('Then run verification again:');
  console.log(`  /ccpm:verify ${issueId}\n`);

  // Update Linear with failure
  // Use the Task tool to add failure comment
  await Task({
    subagent_type: 'ccpm:linear-operations',
    description: 'Add quality check failure comment',
    prompt: `
operation: create_comment
params:
  issueId: "${issueId}"
  body: |
    ## ❌ Quality Checks Failed

    **Results:**
    - ${results.lint ? '✅' : '❌'} Linting
    - ${results.test ? '✅' : '❌'} Tests
    ${buildCommand ? `- ${results.build ? '✅' : '❌'} Build` : ''}

    **Action Required:**
    Fix the issues above, then run \`/ccpm:verify\` again.

    ---
    *Via /ccpm:verify*
context:
  command: "verify"
    `
  });

  return;
}

Step 6: Run Final Verification (if checks passed)

═══════════════════════════════════════
Step 2/2: Running Final Verification
═══════════════════════════════════════

A) Invoke code-reviewer agent with smart agent selection:

Task: `
Review all code changes for issue ${issueId}: ${issue.title}

Context:
- Issue description:
${issue.description}

- All checklist items marked complete

Your task:
1. Review all changes against requirements
2. Check for code quality and best practices
3. Verify security considerations
4. Check for potential regressions
5. Validate error handling
6. Assess performance impact

Provide:
- ✅ What passed review
- ❌ Critical issues (if any)
- 🔍 Recommendations (if any)
- 📊 Overall assessment (PASS/FAIL)
`

Note: Smart agent selector will automatically choose the best agent
(code-reviewer, security-auditor, or specialized reviewer)

B) Parse verification results:

// Look for PASS/FAIL in agent response
const verificationPassed = !response.includes('❌ FAIL') &&
                          !response.includes('Critical issues') &&
                          (response.includes('✅ PASS') || response.includes('All checks passed'));

Step 7: Update Linear Based on Results

If verification PASSED:

Use the Task tool to update Linear issue to Done:

Invoke the ccpm:linear-operations subagent:

• Tool: Task
• Subagent: ccpm:linear-operations
• Prompt:

  operation: update_issue
  params:
    issueId: "{issue ID from step 1}"
    state: "Done"
    labels: ["verified"]
  context:
    command: "verify"
  

Use the Task tool to add success comment:

Invoke the ccpm:linear-operations subagent:

• Tool: Task
• Subagent: ccpm:linear-operations
• Prompt:

  operation: create_comment
  params:
    issueId: "{issue ID from step 1}"
    body: |
      ## ✅ Verification Complete
  
      **Quality Checks:**
      - ✅ Linting: PASS
      - ✅ Tests: PASS
      - ✅ Build: PASS
  
      **Final Verification:**
      - ✅ Code review: PASS
      - ✅ Requirements met
      - ✅ Security validated
      - ✅ Performance acceptable
  
      **Task completed successfully!** 🎉
  
      ---
      *Via /ccpm:verify*
  context:
    command: "verify"
  

If verification FAILED:

Use the Task tool to add failure labels:

Invoke the ccpm:linear-operations subagent:

• Tool: Task
• Subagent: ccpm:linear-operations
• Prompt:

  operation: update_issue
  params:
    issueId: "{issue ID from step 1}"
    labels: ["blocked", "needs-revision"]
  context:
    command: "verify"
  

Use the Task tool to add failure comment:

Invoke the ccpm:linear-operations subagent:

• Tool: Task
• Subagent: ccpm:linear-operations
• Prompt:

  operation: create_comment
  params:
    issueId: "{issue ID from step 1}"
    body: |
      ## ❌ Verification Failed
  
      **Quality Checks:** ✅ PASS
  
      **Final Verification:** ❌ FAIL
  
      **Issues Found:**
      {verification issues from step 6}
  
      **Action Required:**
      Fix the issues above, then run \`/ccpm:verify\` again.
  
      ---
      *Via /ccpm:verify*
  context:
    command: "verify"
  

Step 8: Display Results & Next Actions

If all passed:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ All Verification Complete!
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 Issue: ${issueId} - ${issue.title}
📊 Status: Done

✅ Quality Checks: PASS
✅ Final Verification: PASS

All verifications passed! Ready to finalize.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
💡 What's Next?
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

⭐ Recommended: Finalize task
   /ccpm:done ${issueId}

This will:
  • Create pull request
  • Sync status to Jira (if configured)
  • Send notifications (if configured)
  • Mark task as complete

Or continue making changes:
  /ccpm:work ${issueId}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Interactive menu:

const response = await AskUserQuestion({
  questions: [{
    question: "Verification complete! What would you like to do next?",
    header: "Next Step",
    multiSelect: false,
    options: [
      {
        label: "Finalize Task",
        description: "Create PR and mark as complete (/ccpm:done)"
      },
      {
        label: "Continue Working",
        description: "Make more changes (/ccpm:work)"
      },
      {
        label: "View Status",
        description: "Check current status (/ccpm:utils:status)"
      }
    ]
  }]
});

// Execute chosen action
if (response.answers[0] === "Finalize Task") {
  await SlashCommand(`/ccpm:done ${issueId}`);
} else if (response.answers[0] === "Continue Working") {
  await SlashCommand(`/ccpm:work ${issueId}`);
} else {
  await SlashCommand(`/ccpm:utils:status ${issueId}`);
}

If failed:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
❌ Verification Failed
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📋 Issue: ${issueId} - ${issue.title}

${failureType === 'checks' ? '❌ Quality Checks: FAIL' : '✅ Quality Checks: PASS'}
${failureType === 'verification' ? '❌ Final Verification: FAIL' : ''}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
💡 Next Steps
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

1. Fix the issues (see details above)
2. Run: /ccpm:verification:fix ${issueId}
3. Then verify again: /ccpm:verify ${issueId}

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Error Handling

Invalid Issue ID Format

❌ Invalid issue ID format: proj123
Expected format: PROJ-123 (uppercase letters, hyphen, numbers)

Issue Not Found

❌ Error fetching issue: Issue not found

Suggestions:
  - Verify the issue ID is correct
  - Check you have access to this Linear team
  - Ensure the issue hasn't been deleted

Git Branch Detection Failed

❌ Could not detect issue ID from git branch

Current branch: main

Usage: /ccpm:verify [ISSUE-ID]

Example: /ccpm:verify PSN-29

Project Commands Not Found

⚠️  No lint/test commands found in package.json

Verification requires:
  - "lint" script for linting
  - "test" script for testing

Add these to package.json and try again.

Examples

Example 1: Verify with auto-detection (all passed)

# Current branch: feature/PSN-29-add-auth
/ccpm:verify

# Output:
# 📌 Detected issue from branch: PSN-29
#
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 🔍 Smart Verify Command
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#
# 📋 Issue: PSN-29 - Add user authentication
# 📊 Status: In Progress
# 📋 Checklist: 100% (5/5 items)
#
# ═══════════════════════════════════════
# Step 1/2: Running Quality Checks
# ═══════════════════════════════════════
#
# 🔍 Running linting...
# ✅ All files pass linting
#
# 🧪 Running tests...
# ✅ All tests passed (28/28)
#
# 🏗️  Running build...
# ✅ Build successful
#
# 📊 Quality Check Results:
#   ✅ Linting
#   ✅ Tests
#   ✅ Build
#
# ═══════════════════════════════════════
# Step 2/2: Running Final Verification
# ═══════════════════════════════════════
#
# [Code reviewer agent analyzes changes...]
#
# ✅ All requirements met
# ✅ Code quality standards met
# ✅ Security best practices followed
#
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# ✅ All Verification Complete!
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Example 2: Verify explicit issue (checks failed)

/ccpm:verify PSN-29

# Output:
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
# 🔍 Smart Verify Command
# ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
#
# [... quality checks ...]
#
# 📊 Quality Check Results:
#   ✅ Linting
#   ❌ Tests
#   ✅ Build
#
# ❌ Quality Checks Failed
#
# To debug and fix issues:
#   /ccpm:verification:fix PSN-29
#
# Then run verification again:
#   /ccpm:verify PSN-29

Example 3: Incomplete checklist prompt

/ccpm:verify PSN-29

# Output:
# 📋 Checklist: 80% (4/5 items)
#
# ⚠️  Checklist incomplete!
#
# Remaining items:
#   ⏳ Write integration tests
#
# [Interactive prompt appears:]
# Checklist is 80% complete. What would you like to do?
#   • Continue anyway
#   • Update checklist
#   • Cancel

Token Budget Breakdown

Section	Tokens	Notes
Frontmatter & description	80	Minimal metadata
Step 1: Argument parsing	180	Git detection + validation
Step 2: Fetch issue	120	Linear subagent (cached)
Step 3: Display flow	80	Header + flow diagram
Step 4: Checklist check	250	Parsing + interactive prompt
Step 5: Quality checks	500	Commands + execution + results
Step 6: Final verification	300	Agent invocation + parsing
Step 7: Update Linear	200	Batch update + comment
Step 8: Results display	250	Success/failure + menu
Error handling	200	4 scenarios
Examples	340	3 concise examples
Total	~2,500	vs ~8,000 baseline (69% reduction)

Key Optimizations

1. ✅ No routing overhead - Direct implementation (no /ccpm:verification:check or :verify calls)
2. ✅ Linear subagent - All Linear ops cached (85-95% hit rate)
3. ✅ Smart agent selection - Automatic optimal agent choice for verification
4. ✅ Sequential execution - Checks → verification (fail fast)
5. ✅ Auto-detection - Issue ID from git branch
6. ✅ Batch operations - Single update_issue call (state + labels)
7. ✅ Concise examples - Only 3 essential examples

Integration with Other Commands

• After /ccpm:sync → Use /ccpm:verify to check quality
• After /ccpm:work → Complete work then /ccpm:verify
• Before /ccpm:done → Always verify before finalizing
• Failed checks → Use /ccpm:verification:fix to debug

Notes

• Git branch detection: Extracts issue ID from branch names like feature/PSN-29-add-auth
• Smart agent selection: Automatically invokes optimal verification agent
• Fail fast: Stops at quality checks if they fail (no wasted verification)
• Checklist validation: Prompts user if checklist incomplete
• Caching: Linear subagent caches issue data for faster operations
• Error recovery: Provides actionable suggestions for all error scenarios