Idea Intake Workflow - Unified Interface Skill

Idea Intake Workflow - Unified Interface

Purpose

Single command interface for Matt Maher's "do-work" autonomous idea intake pattern. Provides unified access to capture, validation, and processing operations without needing to remember multiple commands across different skills.

This skill orchestrates three sub-skills into a cohesive workflow:

idea-queue-capture - Fast idea capture
Senior PM Enhanced (validation) - Feasibility assessment and routing
work-queue-processor - Autonomous execution

Philosophy

One command to rule them all: /workflow with intelligent subcommands that handle the entire lifecycle from idea capture to execution and archival.

Context Isolation: Each phase runs in isolated contexts to prevent pollution and maintain predictable behaviour:

Capture Claude: Instant idea collection (no planning overhead)
Work Claude: Autonomous execution with fresh sub-agents per item
Validation: Runs in either instance with proper state tracking

Quick Start Guide

For First-Time Users

Capture an idea: Simply type your idea naturally, then use /workflow capture
Validate ideas: Use /workflow validate to have Senior PM assess feasibility and assign agents
Process validated work: Use /workflow process to autonomously execute validated items
Monitor progress: Use /workflow status to see what's happening in real-time

Common Workflows

Rapid capture mode (Capture Claude):

User: Fix the navigation padding on mobile
/workflow capture

User: Also analyze R&D transactions for FY2023-24
/workflow capture

User: And add dark mode toggle to settings
/workflow capture

Autonomous execution mode (Work Claude):

/workflow process --continuous

(Runs until queue empty or tokens exhausted)

Quick status check:

/workflow status

Commands

`/workflow` (no args)

Shows interactive menu with current queue status and available commands.

Output:

🔄 Idea Intake Workflow v2.0.0

Current Queue Status:
├─ Pending:    3 items (awaiting validation)
├─ Validated:  2 items (ready to process)
├─ Processing: 1 item  (currently executing)
└─ Completed:  15 items (archived)

Available Commands:
├─ /workflow capture   - Capture the current message as an idea
├─ /workflow validate  - Validate all pending items (PM review)
├─ /workflow process   - Process validated items (execute work)
├─ /workflow status    - Show detailed queue status
└─ /workflow stats     - Show performance statistics

💡 Quick Actions:
- To capture current message: /workflow capture
- To validate all pending: /workflow validate
- To process everything: /workflow process --continuous
- To see what's happening: /workflow status

📚 Documentation: .agent/skills/idea-intake-workflow/SKILL.md

When to use:

First time using the system
Forgot available subcommands
Need quick overview of queue state

Aliases: None (canonical form only)

`/workflow capture`

Captures the current user message (or previous message if empty) as an idea to the work queue.

Aliases: capture, add, queue, idea

Process:

Extract user's most recent message (or use provided text)
Auto-detect type (feature/bug/improvement/task/client_request)
Generate concise title (max 80 chars)
Apply intelligent grouping if multiple related ideas detected
Write to Supabase work_queue with status='pending'
Return confirmation with queue ID and position

Implementation:

import { addToQueue } from '@/lib/queue/work-queue-manager';

// Capture idea
const queueItem = await addToQueue({
  title: generatedTitle,
  description: userInputVerbatim,
  queue_item_type: detectedType,
  payload: {
    original_message: userInput,
    context: currentContext,
    timestamp: new Date().toISOString(),
    source: 'workflow-capture',
  },
});

console.log(`✅ Captured: ${queueItem.title} (ID: ${queueItem.id})`);

Example 1 - Simple Bug:

User: The navigation header has too much padding on mobile devices
User: /workflow capture

Claude: ✅ Idea captured successfully!

**Title**: Fix navigation header padding on mobile
**Type**: Bug
**Queue position**: #3
**Status**: Pending validation

Next: The Senior PM agent will validate this idea and assign it to an agent.

Example 2 - Multiple Related Ideas (Grouped):

User: The description panel has two issues:
1. The copy icon overlaps with text
2. There's not enough spacing between sections
User: /workflow capture

Claude: ✅ Idea captured successfully!

**Title**: Fix description panel UI issues
**Type**: Bug
**Queue position**: #4
**Status**: Pending validation

Note: Grouped 2 related issues affecting the same component.
Next: Senior PM will validate and route to the appropriate agent.

Example 3 - Multiple Unrelated Ideas (Separated):

User: Fix the copy icon overlap. Also, analyze R&D transactions for FY2023-24.
User: /workflow capture

Claude: ✅ 2 ideas captured successfully!

1. **Fix copy icon overlap** (Bug) - Position #5
2. **Analyze R&D transactions for FY2023-24** (Feature) - Position #6

Note: Created separate items since these are different domains (UI vs tax analysis).
Next: Senior PM will validate both ideas.

Example 4 - Explicit Text Capture:

User: /workflow capture Add dark mode toggle to settings page

Claude: ✅ Idea captured successfully!

**Title**: Add dark mode toggle to settings page
**Type**: Feature
**Queue position**: #7
**Status**: Pending validation

Next: Senior PM will validate and assess feasibility.

Options:

--text "..." - Capture specific text instead of previous message
--type <type> - Override auto-detection (feature|bug|improvement|client_request|task)
--separate - Force multiple ideas to be separate items (disable grouping)

Error Handling:

❌ Failed to capture idea

Error: Database connection failed

Suggestions:
- Check SUPABASE_SERVICE_ROLE_KEY is configured
- Verify Supabase project is running
- Run migration: supabase migration up

Your idea has not been lost. Please try again or contact support.

`/workflow validate`

Validates all pending queue items using Senior PM Enhanced agent. Performs feasibility assessment, complexity analysis, duplicate detection, priority assignment, and agent routing.

Aliases: validate, review, pm-review

Process:

Fetch all pending items from work_queue (status='pending')
For each item: a. Assess feasibility (0-100 score) b. Determine complexity (simple/medium/complex) c. Check for duplicates in Linear d. Assign priority (P0/P1/P2/P3) e. Route to domain agent f. Determine execution strategy (direct/requires_planning/specialist_review) g. Calculate confidence score
Mark items as 'validated' with validation_result
Optionally create Linear issues if not duplicates
Return summary of validated items

Implementation:

import { getQueueItemsByStatus, markAsValidating, markAsValidated } from '@/lib/queue/work-queue-manager';
import { validateQueueItem } from '@/lib/queue/pm-validator';

// Fetch pending items
const pendingItems = await getQueueItemsByStatus('pending');

for (const item of pendingItems) {
  // Mark as validating
  await markAsValidating(item.id);

  // Run validation
  const validationResult = await validateQueueItem(item);

  // Mark as validated
  await markAsValidated(item.id, validationResult);

  console.log(`✅ Validated: ${item.title}`);
  console.log(`   Complexity: ${validationResult.complexity}`);
  console.log(`   Priority: ${validationResult.priority}`);
  console.log(`   Agent: ${validationResult.assigned_agent}`);
}

Example 1 - Single Item Validation:

User: /workflow validate

Claude: 🔍 Starting validation of pending items...

Validating: Fix navigation header padding on mobile

**Feasibility Score**: 85/100
- Frontend changes are straightforward with existing patterns
- UI component change with minimal risk

**Complexity**: Simple
- Single file change, straightforward implementation

**Priority**: P2 (Medium)
- Bug fix, affects user experience

**Assigned Agent**: general
- No specialist required

**Execution Strategy**: Direct
- Can execute immediately without planning phase

**Confidence**: 80%

**Duplicate Check**: No duplicates found

✅ Validation complete! Item ready for processing.

Status changed: pending → validated

Example 2 - Multiple Items with Duplicate Detection:

User: /workflow validate

Claude: 🔍 Starting validation of pending items...

[1/3] Validating: Fix description panel spacing

**Feasibility Score**: 90/100
**Complexity**: Simple
**Priority**: P2
**Agent**: general
**Strategy**: Direct
**Confidence**: 85%
**Duplicate**: ⚠️ Similar to UNI-42 (87% match)

Action: Merging context into existing Linear issue UNI-42
Status: Marked as duplicate, will not create new issue

---

[2/3] Validating: Analyze R&D transactions for FY2023-24

**Feasibility Score**: 95/100
- Xero integration available for data extraction
- R&D Tax Incentive specialist available

**Complexity**: Complex
- Significant analysis required, multiple files affected

**Priority**: P1 (High)
- R&D registration deadline approaching

**Assigned Agent**: rnd-tax-specialist
- Routed to R&D specialist for Division 355 analysis

**Execution Strategy**: Specialist Review
- Requires user approval before execution due to complexity

**Confidence**: 90%
**Duplicate**: No duplicates found

Action: Creating Linear issue...
✅ Created: UNI-45 - Analyze R&D transactions for FY2023-24

---

[3/3] Validating: Add dark mode toggle to settings

**Feasibility Score**: 85/100
**Complexity**: Medium
**Priority**: P3 (Low)
**Agent**: general
**Strategy**: Requires Planning
- Requires planning sub-agent before execution

**Confidence**: 80%
**Duplicate**: No duplicates found

Action: Creating Linear issue...
✅ Created: UNI-46 - Add dark mode toggle to settings

---

📊 Validation Summary
- Total pending: 3 items
- Validated: 3 items
- Duplicates: 1 item
- Linear issues created: 2 items
- Ready for execution: 3 items (2 new, 1 merged)

Next: Use `/workflow process` to start autonomous execution

Options:

--batch <N> - Validate max N items (default: all pending)
--create-issues - Create Linear issues immediately (default: true)
--skip-duplicates - Skip duplicate checking (faster, not recommended)

Validation Criteria:

| Criterion | Thresholds | Action | |-----------|------------|--------| | Feasibility Score | < 50 | Mark as not feasible, require user review | | Feasibility Score | 50-79 | Mark as feasible with notes | | Feasibility Score | 80-100 | Mark as highly feasible | | Duplicate Similarity | > 70% | Flag as duplicate, merge context | | Duplicate Similarity | 50-70% | Flag as potential duplicate, notify user | | Duplicate Similarity | < 50% | Not a duplicate |

Error Handling:

❌ Validation failed for: Analyze R&D transactions

Error: Linear API connection failed

Action: Marked as 'validating' (will retry)
Suggestion: Check LINEAR_API_KEY and retry

Continuing with other items...

`/workflow process`

Processes all validated queue items autonomously using the work-queue-processor pattern. Spawns fresh sub-agent contexts for each item to avoid context pollution.

Aliases: process, execute, work, do-work

Process:

Fetch next validated item (status='validated', ordered by priority then creation time)
Mark item as 'processing'
Create Linear issue if not exists
Route based on complexity:
- Simple: Execute directly
- Medium: PLANNER sub-agent → EXECUTOR sub-agent
- Complex: PLANNER sub-agent → USER APPROVAL → EXECUTOR sub-agent
Update Linear status as work progresses
Capture before/after screenshots
Mark as 'complete' or 'failed'
Archive if complete
Repeat until queue empty or stopped

Implementation:

import { getNextValidatedItem, markAsProcessing, markAsComplete, markAsFailed } from '@/lib/queue/work-queue-manager';
import { createIssue, updateIssue } from '@/lib/linear/api-client';

// Orchestrator loop
while (true) {
  // Fetch next item
  const item = await getNextValidatedItem();
  if (!item) {
    console.log('Queue is empty');
    break;
  }

  // Mark as processing
  await markAsProcessing(item.id);

  // Create Linear issue if needed
  if (!item.linear_issue_id) {
    const issue = await createIssue(buildIssueFromQueue(item));
    await updateLinearMetadata(item.id, {
      issue_id: issue.id,
      issue_identifier: issue.identifier,
      issue_url: issue.url,
    });
  }

  // Execute based on complexity
  try {
    let result;
    if (item.complexity === 'simple') {
      result = await executeSimpleTask(item);
    } else if (item.complexity === 'medium') {
      const plan = await spawnPlannerSubAgent(item);
      result = await spawnExecutorSubAgent(item, plan);
    } else {
      const plan = await spawnPlannerSubAgent(item);
      const approved = await askUserForApproval(plan);
      if (!approved) {
        await markAsFailed(item.id, 'User rejected plan');
        continue;
      }
      result = await spawnExecutorSubAgent(item, plan);
    }

    // Mark as complete
    await markAsComplete(item.id, result);
    await updateIssue(item.linear_issue_id, {
      stateId: await getStateIdByType('completed'),
    });

  } catch (error) {
    // Mark as failed
    await markAsFailed(item.id, error.message);
    await updateIssue(item.linear_issue_id, {
      stateId: await getStateIdByType('canceled'),
    });
  }

  // Rate limit (4-second delay)
  await sleep(4000);
}

Example 1 - Simple Item (Direct Execution):

User: /workflow process

Claude: ⚙️ Work Queue Processor Started

[1/3] Processing: Fix navigation header padding on mobile (UNI-43)
- Complexity: simple
- Strategy: Direct execution (no planning needed)

Executing...
- Reading: app/components/Navigation.tsx
- Analyzing: Current padding values
- Updating: Mobile breakpoint padding from 20px to 12px
- Testing: Visual verification

✅ Complete! (3 minutes)

Changes:
- Updated: app/components/Navigation.tsx (1 file, 3 lines changed)
- Before screenshot: .queue/screenshots/uuid-123/before.png
- After screenshot: .queue/screenshots/uuid-123/after.png

Linear: https://linear.app/unite-hub/issue/UNI-43
Status: Complete → Archived

---

[2/3] Processing: Add dark mode toggle to settings (UNI-46)
- Complexity: medium
- Strategy: Requires planning
- Agent: general

Spawning PLANNER sub-agent...

📋 Plan Created:
1. Create ThemeContext provider with light/dark state
2. Create ThemeToggle component with switch UI
3. Update existing components to read from ThemeContext
4. Add CSS variables for theme colors
5. Persist theme preference to localStorage

✓ Plan approved automatically (medium complexity)

Spawning EXECUTOR sub-agent...

Executing plan...
- Created: lib/theme/ThemeContext.tsx
- Created: components/ThemeToggle.tsx
- Updated: app/layout.tsx (wrap with ThemeProvider)
- Updated: 8 components to use theme colors
- Added: CSS variables in globals.css
- Added: localStorage persistence

Testing dark mode...
✅ Light mode works
✅ Dark mode works
✅ Theme persists on reload

✅ Complete! (12 minutes)

Changes:
- Created: 2 files
- Updated: 10 files
- Total lines: 247 lines changed

Linear: https://linear.app/unite-hub/issue/UNI-46
Status: Complete → Archived

---

[3/3] Processing: Analyze R&D transactions for FY2023-24 (UNI-45)
- Complexity: complex
- Strategy: Specialist review required
- Agent: rnd-tax-specialist

Spawning PLANNER sub-agent (rnd-tax-specialist)...

📋 Plan Created:
1. Fetch all Xero transactions for FY2023-24 (July 1, 2023 - June 30, 2024)
2. Filter for potential R&D expenditure (development, research, consulting)
3. Apply Division 355 four-element test to each transaction
4. Calculate eligible expenditure
5. Calculate R&D tax offset (43.5% for turnover < $20M)
6. Generate compliance report with legislative references
7. Flag transactions requiring further review

Estimated value: $200K-$500K potential refund

⚠️ This is a complex analysis involving significant financial value.

Proceed with execution? [Yes/No]

User: Yes

✓ Approved by user

Spawning EXECUTOR sub-agent (rnd-tax-specialist)...

Executing R&D analysis...
- Fetching Xero transactions (July 1, 2023 - June 30, 2024)...
- Retrieved: 1,247 transactions
- Filtering for potential R&D expenditure...
- Found: 387 potential R&D transactions

Applying Division 355 four-element test...
- Test 1 (New Knowledge): 256 transactions pass
- Test 2 (Outcome Unknown): 198 transactions pass
- Test 3 (Systematic Approach): 167 transactions pass
- Test 4 (Scientific Method): 127 transactions pass

✅ Eligible: 127 transactions

Calculating tax benefit...
- Total eligible expenditure: $293,000
- R&D tax offset (43.5%): $127,455
- Potential refund: $127,455

Generating compliance report...
- Transaction breakdown by category
- Four-element test results per transaction
- Legislative references (Division 355 ITAA 1997)
- Registration deadline: April 30, 2025
- Professional review recommendations

✅ Complete! (18 minutes)

Analysis Summary:
- Transactions analyzed: 1,247
- Eligible R&D transactions: 127
- Eligible expenditure: $293,000
- Tax offset: $127,455
- Confidence: High (90%)

Report saved: .queue/reports/rnd-analysis-fy2023-24.pdf

⚠️ Recommendations:
- Professional review required before submission
- Register with AusIndustry before April 30, 2025
- 15 transactions flagged for further documentation

Linear: https://linear.app/unite-hub/issue/UNI-45
Status: Complete → Archived

---

📊 Session Complete

Processed: 3 items
Succeeded: 3 items (100%)
Failed: 0 items
Total time: 33 minutes
Tokens used: ~18,500 PTS

Queue status:
- Pending: 0 items
- Validated: 0 items
- Processing: 0 items

All items complete! 🎉

Example 2 - Continuous Mode:

User: /workflow process --continuous

Claude: ⚙️ Work Queue Processor Started (Continuous Mode)

Will process items continuously until queue empty or tokens exhausted.

Press Ctrl+C or use /workflow pause to stop gracefully.

---

[1/10] Processing: Fix copy icon overlap (UNI-42)
...
✅ Complete! (2 minutes)

[2/10] Processing: Update form validation (UNI-47)
...
✅ Complete! (8 minutes)

[3/10] Processing: Refactor tax calculation logic (UNI-48)
...
⚙️ Processing... (45% complete)

(Continues until queue empty)

---

📊 Session Complete

Processed: 10 items
Succeeded: 9 items (90%)
Failed: 1 item (10%)
Total time: 87 minutes
Tokens used: ~42,300 PTS
Tokens remaining: ~47,700 PTS

Queue status: Empty

Next: Use /workflow capture to add more ideas

Options:

--continuous - Run until queue empty or tokens exhausted
--limit <N> - Process maximum N items then stop
--priority <P> - Only process items with specific priority (P0/P1/P2/P3)
--agent <name> - Only process items assigned to specific agent

Error Handling:

When an item fails:

❌ Execution failed: Add dark mode toggle (UNI-46)

Error: Component ThemeContext.tsx already exists
Retry count: 1/3

Action:
- Marked as 'failed' with error message
- Updated Linear issue to 'Canceled'
- Added comment to Linear with error details

The work loop will continue with the next item.
To retry failed items, use /workflow retry

When token budget is low:

⚠️ Token budget low (8,500 PTS remaining)

Action: Pausing work loop gracefully
Status: Saved processor state

Items processed this session: 8
Items remaining in queue: 2

To resume: /workflow process

Performance Targets:

| Metric | Target | |--------|--------| | Simple item execution | < 5 minutes | | Medium item execution | < 15 minutes | | Complex item execution | < 30 minutes | | Queue throughput | 10-25 items per 90 minutes | | Success rate | > 95% | | Token usage per item | 50-500 PTS |

`/workflow status`

Shows detailed breakdown of current queue status, including what's currently processing, items in each state, and recent completions.

Aliases: status, queue, progress

Process:

Fetch queue statistics from work_queue table
Get currently processing item (if any)
Get recent completions (last 5)
Calculate estimated time remaining
Show breakdown by status

Implementation:

import { getQueueStatistics, getQueueItemsByStatus } from '@/lib/queue/work-queue-manager';

// Get statistics
const stats = await getQueueStatistics();

// Get currently processing
const processingItems = await getQueueItemsByStatus('processing', 1);
const currentItem = processingItems[0] || null;

// Get recent completions
const recentCompletions = await getQueueItemsByStatus('complete', 5);

// Display status
console.log('📊 Queue Status\n');
if (currentItem) {
  console.log('Currently processing:');
  console.log(`- ${currentItem.title} (${currentItem.linear_issue_identifier})`);
  console.log(`- Progress: Executing...`);
  console.log(`- Time elapsed: ${calculateElapsed(currentItem.updated_at)}\n`);
}

console.log('Queue breakdown:');
console.log(`├─ Pending:    ${stats.pending_count} items`);
console.log(`├─ Validating: ${stats.validating_count} items`);
console.log(`├─ Validated:  ${stats.validated_count} items (ready to process)`);
console.log(`├─ Processing: ${stats.processing_count} items`);
console.log(`├─ Complete:   ${stats.complete_count} items`);
console.log(`├─ Failed:     ${stats.failed_count} items`);
console.log(`└─ Archived:   ${stats.archived_count} items\n`);

Example Output:

User: /workflow status

Claude: 📊 Queue Status

Currently processing:
- Analyze R&D transactions for FY2023-24 (UNI-45)
- Progress: Applying Division 355 test (67% complete)
- Time elapsed: 12 minutes
- Agent: rnd-tax-specialist

Queue breakdown:
├─ Pending:    2 items (awaiting validation)
├─ Validating: 0 items
├─ Validated:  3 items (ready to process)
├─ Processing: 1 item  (currently executing)
├─ Complete:   25 items
├─ Failed:     1 item
└─ Archived:   22 items

Recently completed:
1. Fix navigation header padding (UNI-43) - 15 mins ago ✅
2. Update form validation (UNI-47) - 23 mins ago ✅
3. Refactor tax calculation (UNI-48) - 45 mins ago ✅
4. Add user authentication (UNI-49) - 1 hour ago ✅
5. Fix database migration (UNI-50) - 2 hours ago ✅

Session statistics:
- Items processed today: 8
- Success rate: 87.5%
- Average execution time: 9.3 minutes
- Total token usage: 24,500 PTS

Estimated time for validated items: ~45 minutes

Next in queue:
1. Add dark mode toggle (UNI-46) - P3 - Medium complexity
2. Fix copy icon overlap (UNI-51) - P2 - Simple
3. Create export functionality (UNI-52) - P1 - Complex

To process validated items: /workflow process
To see detailed statistics: /workflow stats

When to use:

Check what's currently happening
See queue backlog
Monitor progress during long processing sessions
Verify items were captured/validated
Check estimated completion time

`/workflow stats`

Shows detailed performance statistics and metrics for the idea intake workflow system.

Aliases: stats, metrics, performance, analytics

Process:

Fetch queue statistics from database
Calculate performance metrics (success rate, execution time, token usage)
Break down by complexity, priority, agent
Show validation statistics
Display trends over time

Implementation:

import { getQueueStatistics, getQueueItemsByStatus } from '@/lib/queue/work-queue-manager';
import { calculateValidationStats } from '@/lib/queue/pm-validator';

// Get statistics
const stats = await getQueueStatistics();

// Get all validated items for PM stats
const validatedItems = await getQueueItemsByStatus('validated');
const pmStats = calculateValidationStats(validatedItems);

// Calculate success rate
const totalProcessed = stats.complete_count + stats.failed_count;
const successRate = totalProcessed > 0
  ? (stats.complete_count / totalProcessed * 100).toFixed(1)
  : 0;

// Display stats
console.log('📊 Workflow Statistics\n');
console.log('Overall Performance:');
console.log(`- Total items processed: ${totalProcessed}`);
console.log(`- Success rate: ${successRate}%`);
console.log(`- Average execution time: ${stats.avg_execution_time_seconds}s`);
console.log(`- Total token usage: ${stats.total_token_usage} PTS\n`);

console.log('By Complexity:');
console.log(`- Simple: ${pmStats.by_complexity.simple} items`);
console.log(`- Medium: ${pmStats.by_complexity.medium} items`);
console.log(`- Complex: ${pmStats.by_complexity.complex} items\n`);

Example Output:

User: /workflow stats

Claude: 📊 Workflow Statistics

Overall Performance:
- Total items processed: 127
- Success rate: 96.8% (123 succeeded, 4 failed)
- Average execution time: 8.3 minutes
- Total token usage: 45,230 PTS
- Average tokens per item: 356 PTS

Status Breakdown:
├─ Pending:    3 items (2.3%)
├─ Validating: 0 items (0%)
├─ Validated:  2 items (1.6%)
├─ Processing: 1 item  (0.8%)
├─ Complete:   119 items (93.7%)
├─ Failed:     2 items (1.6%)
└─ Archived:   115 items (90.6%)

By Complexity:
├─ Simple:   47 items (37.0%) - Avg time: 3.2 mins
├─ Medium:   58 items (45.7%) - Avg time: 9.1 mins
└─ Complex:  22 items (17.3%) - Avg time: 21.4 mins

By Priority:
├─ P0 (Critical): 2 items (1.6%)
├─ P1 (High):     28 items (22.0%)
├─ P2 (Medium):   74 items (58.3%)
└─ P3 (Low):      23 items (18.1%)

By Assigned Agent:
├─ general:                    67 items (52.8%)
├─ rnd-tax-specialist:         18 items (14.2%)
├─ deduction-optimizer:        12 items (9.4%)
├─ xero-auditor:               11 items (8.7%)
├─ loss-recovery-agent:        8 items (6.3%)
├─ trust-distribution-analyzer: 5 items (3.9%)
└─ Other specialists:          6 items (4.7%)

Validation Statistics:
- Average feasibility score: 82/100
- Average confidence: 78/100
- Duplicate detection rate: 12% (15 duplicates found)

Execution Strategy:
- Direct execution: 47 items (37.0%)
- Requires planning: 58 items (45.7%)
- Specialist review: 22 items (17.3%)

Recent Trends (Last 24 Hours):
- Items captured: 15
- Items validated: 12
- Items processed: 10
- Success rate: 100%
- Average time per item: 7.2 minutes

Time Distribution:
- 0-5 minutes:   47 items (37.0%)
- 5-10 minutes:  38 items (29.9%)
- 10-15 minutes: 20 items (15.7%)
- 15-30 minutes: 18 items (14.2%)
- 30+ minutes:   4 items (3.1%)

Token Distribution:
- 0-100 PTS:    52 items (40.9%)
- 100-500 PTS:  61 items (48.0%)
- 500-1000 PTS: 12 items (9.4%)
- 1000+ PTS:    2 items (1.6%)

Failed Items Analysis:
- Database connection: 1 item
- User canceled: 1 item
- Total failed: 2 items (1.6%)

Top Performing Categories:
1. UI/Frontend changes: 98% success rate (3.8 min avg)
2. Tax analysis: 95% success rate (18.2 min avg)
3. Database changes: 87% success rate (12.4 min avg)

Recommendations:
✅ High capture rate - system is being used effectively
✅ Excellent success rate (96.8%) - execution quality is strong
⚠️ 12% duplicate rate - consider improving capture descriptions
✅ Token usage is efficient (356 PTS avg per item)

When to use:

Periodic performance review
Understanding system usage patterns
Identifying bottlenecks or issues
Reporting metrics to stakeholders
Optimizing workflow processes

Implementation Notes

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                    /workflow Command                         │
│                    (Orchestrator Skill)                      │
└───────────────┬─────────────────────────────────────────────┘
                │
                ├─ /workflow capture
                │  └─ Uses: lib/queue/work-queue-manager.ts
                │     └─ Function: addToQueue()
                │
                ├─ /workflow validate
                │  └─ Uses: lib/queue/pm-validator.ts
                │     └─ Function: validateQueueItem()
                │     └─ Function: checkForDuplicates()
                │     └─ Uses: lib/linear/api-client.ts
                │
                ├─ /workflow process
                │  └─ Uses: lib/queue/work-queue-manager.ts
                │     └─ Function: getNextValidatedItem()
                │     └─ Function: markAsProcessing()
                │     └─ Function: markAsComplete()
                │     └─ Function: markAsFailed()
                │     └─ Uses: lib/linear/api-client.ts
                │
                ├─ /workflow status
                │  └─ Uses: lib/queue/work-queue-manager.ts
                │     └─ Function: getQueueStatistics()
                │     └─ Function: getQueueItemsByStatus()
                │
                └─ /workflow stats
                   └─ Uses: lib/queue/work-queue-manager.ts
                      └─ Function: getQueueStatistics()
                      └─ Uses: lib/queue/pm-validator.ts
                         └─ Function: calculateValidationStats()

Key Dependencies

Database (Supabase):

Table: work_queue (created by migration 20260129_create_work_queue.sql)
Service Client: lib/supabase/server.ts
Functions:
- get_next_pending_queue_item() - Row-level locking with SKIP LOCKED
- get_next_validated_queue_item() - Priority-sorted with locking
- get_queue_statistics() - Aggregated statistics

Queue Manager (lib/queue/work-queue-manager.ts):

addToQueue() - Add new items
getNextPendingItem() - Fetch for validation
getNextValidatedItem() - Fetch for execution
markAsValidating(), markAsValidated(), markAsProcessing(), markAsComplete(), markAsFailed() - Status transitions
archiveQueueItem() - Archive completed items
updateLinearMetadata() - Store Linear issue references
getQueueStatistics() - Performance metrics
getQueueItemsByStatus() - Filter by status
timeoutStuckItems() - Safety mechanism for stuck items

PM Validator (lib/queue/pm-validator.ts):

validateQueueItem() - Main validation pipeline
assessFeasibility() - Feasibility scoring (0-100)
assessComplexity() - Complexity detection (simple/medium/complex)
assignPriority() - Priority assignment (P0/P1/P2/P3)
determineAssignedAgent() - Agent routing logic
determineExecutionStrategy() - Execution strategy (direct/planning/review)
checkForDuplicates() - Linear duplicate detection
calculateValidationStats() - Validation metrics

Linear Integration (lib/linear/api-client.ts):

createIssue() - Create Linear issue from queue item
updateIssue() - Update issue status
searchIssues() - Search for duplicates
addComment() - Add comments to issues
getStateIdByType() - Get workflow state IDs

Linear Utilities (lib/linear/graphql-queries.ts):

buildIssueFromQueue() - Convert queue item to Linear issue format
extractSearchKeywords() - Extract keywords for duplicate search
findPotentialDuplicates() - Similarity matching
mapQueueStatusToLinearState() - Status mapping

Data Flow

Capture Flow:

User message
  → Parse and extract ideas
  → Auto-detect type
  → Generate title
  → addToQueue() → Supabase work_queue
  → Return confirmation

Validation Flow:

Pending items
  → getQueueItemsByStatus('pending')
  → For each item:
     → markAsValidating()
     → validateQueueItem()
       → assessFeasibility()
       → assessComplexity()
       → checkForDuplicates() → Linear API
       → assignPriority()
       → determineAssignedAgent()
       → determineExecutionStrategy()
     → markAsValidated()
     → Create Linear issue if not duplicate
  → Return summary

Processing Flow:

Validated items
  → getNextValidatedItem() (with row locking)
  → markAsProcessing()
  → Create Linear issue if needed
  → Route based on complexity:
     → Simple: executeSimpleTask()
     → Medium: spawnPlannerSubAgent() → spawnExecutorSubAgent()
     → Complex: spawnPlannerSubAgent() → askUserForApproval() → spawnExecutorSubAgent()
  → markAsComplete() or markAsFailed()
  → updateIssue() → Linear API
  → archiveQueueItem() (if complete)
  → Repeat

Error Handling Patterns

Database Errors:

try {
  const item = await addToQueue({ ... });
  return { status: 'success', item };
} catch (error) {
  console.error('Failed to add item to queue:', error);
  return {
    status: 'error',
    error: error.message,
    suggestions: [
      'Check SUPABASE_SERVICE_ROLE_KEY is configured',
      'Verify Supabase project is running',
      'Run migration: supabase migration up'
    ]
  };
}

Linear API Errors:

try {
  const duplicateCheck = await checkForDuplicates(item);
} catch (error) {
  console.warn('Duplicate check failed, continuing without:', error);
  // Graceful degradation - assume not duplicate
  duplicateCheck = { isDuplicate: false };
}

Execution Failures:

try {
  const result = await executeQueueItem(item);
  await markAsComplete(item.id, result);
} catch (error) {
  console.error(`Execution failed for ${item.id}:`, error);
  await markAsFailed(item.id, error.message);

  // Update Linear
  await updateIssue(item.linear_issue_id, {
    stateId: await getStateIdByType('canceled'),
  });
  await addComment(item.linear_issue_id,
    `Execution failed: ${error.message}\n\nMarked as failed in queue.`
  );

  // Continue to next item (don't stop loop)
  continue;
}

Token Exhaustion:

const estimatedRemainingTokens = calculateRemainingTokens();

if (estimatedRemainingTokens < MIN_TOKEN_THRESHOLD) {
  console.warn('Token budget low, stopping gracefully');

  await saveProcessorState({
    lastProcessedId: item.id,
    itemsProcessed: count,
    timestamp: new Date().toISOString(),
  });

  return {
    status: 'paused',
    reason: 'token_budget_low',
    itemsProcessed: count,
    message: 'Work loop paused due to low token budget. Restart to continue.',
  };
}

Configuration

Environment Variables:

# Database (Required)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_SERVICE_ROLE_KEY=your-service-role-key

# Linear Integration (Required for validation/processing)
LINEAR_API_KEY=lin_api_...
LINEAR_TEAM_ID=UNI
LINEAR_PROJECT_ID=project-id-optional

# Queue Configuration (Optional)
QUEUE_BATCH_SIZE=10              # Max items per validation/processing session
QUEUE_POLL_INTERVAL_MS=5000      # How often to check for new items
QUEUE_MAX_RETRIES=3              # Max retries on failure
QUEUE_TIMEOUT_HOURS=2            # Mark as failed after N hours in 'processing'
MIN_TOKEN_THRESHOLD=10000        # Stop processing if tokens < this

Rate Limiting:

Linear API: 4-second delay between calls (follows Gemini pattern)
Supabase: No rate limiting (self-hosted or generous limits)
Token Budget: Stop if < 10,000 PTS remaining

Security Considerations

Database Access:

Uses SUPABASE_SERVICE_ROLE_KEY (bypasses RLS)
No user authentication required (internal tool)
Queue items are not user-specific (shared queue)

Sensitive Data Handling:

Capture preserves user input verbatim (including sensitive data)
Warn user if sensitive information detected
Linear issues created in private team workspace
Execution logs may contain sensitive context

Prohibited Actions (never executed, even if in queue):

Deleting production data
Modifying Xero data (read-only)
Submitting ATO filings
Committing secrets to git
Force-pushing to main branch

Performance Optimization

Database Queries:

Use row-level locking (FOR UPDATE SKIP LOCKED) to prevent race conditions
Index on status column for fast filtering
Index on created_at for queue ordering
Index on priority for priority-based processing

Caching:

Cache queue statistics for 60 seconds
Cache Linear team/project IDs for session
No caching of queue items (always fetch fresh)

Batching:

Validate items in batches (default: all pending)
Process items one at a time (sequential for isolation)
Rate limit Linear API calls (4-second delay)

Token Management:

Estimate tokens per item (50-500 PTS)
Stop if < 10,000 PTS remaining
Save processor state for resumption

Testing Checklist

Capture Tests

[ ] Can capture single idea from user message
[ ] Can capture explicit text with --text option
[ ] Auto-detects correct type (feature/bug/improvement/task/client_request)
[ ] Generates concise title (< 80 chars)
[ ] Groups related ideas correctly
[ ] Separates unrelated ideas correctly
[ ] Handles database connection errors gracefully
[ ] Warns user about sensitive information
[ ] Returns correct queue position
[ ] Stores full context in payload

Validation Tests

[ ] Fetches all pending items
[ ] Assesses feasibility correctly (0-100 score)
[ ] Detects complexity (simple/medium/complex)
[ ] Assigns priority (P0/P1/P2/P3)
[ ] Routes to correct agent
[ ] Determines execution strategy correctly
[ ] Checks for duplicates in Linear
[ ] Creates Linear issues if not duplicate
[ ] Merges context into existing issues if duplicate
[ ] Handles Linear API errors gracefully
[ ] Marks items as validated with validation_result
[ ] Returns summary with all validated items

Processing Tests

[ ] Fetches validated items with row locking
[ ] Processes items in priority order
[ ] Executes simple items directly
[ ] Plans and executes medium items
[ ] Asks user approval for complex items
[ ] Spawns fresh sub-agents per item
[ ] Updates Linear status as work progresses
[ ] Captures before/after screenshots
[ ] Marks items as complete with metadata
[ ] Marks items as failed on error
[ ] Archives completed items
[ ] Continues on individual item failure
[ ] Stops when queue empty
[ ] Stops when token budget low
[ ] Respects rate limits (4-second delay)

Status Tests

[ ] Shows currently processing item
[ ] Shows queue breakdown by status
[ ] Shows recent completions
[ ] Calculates estimated time remaining
[ ] Displays next items in queue
[ ] Handles empty queue correctly

Stats Tests

[ ] Calculates overall performance metrics
[ ] Breaks down by complexity
[ ] Breaks down by priority
[ ] Breaks down by agent
[ ] Shows validation statistics
[ ] Shows execution strategy distribution
[ ] Shows time distribution
[ ] Shows token distribution
[ ] Shows failed items analysis
[ ] Provides recommendations

Troubleshooting

Common Issues

Issue: "Failed to add item to queue: Database connection failed"

Solution:

Check SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY are configured
Verify Supabase project is running
Run migration: supabase migration up
Check network connectivity

Issue: "Duplicate check failed, continuing without"

Solution:

Check LINEAR_API_KEY is configured
Verify Linear team/project IDs are correct
Check Linear API rate limits
This is a warning, not an error - validation continues

Issue: "Execution failed: Component already exists"

Solution:

Item marked as failed, work loop continues
Review error message in Linear issue comment
Fix issue manually or adjust queue item
Use /workflow retry to retry failed items

Issue: "Token budget low, stopping gracefully"

Solution:

This is expected behaviour, not an error
Processor state saved automatically
Use /workflow process to resume
Consider processing fewer items per session with --limit

Issue: "No items in queue" when expecting items

Solution:

Check status with /workflow status
Items may be in different status (pending, validating, processing)
Use /workflow validate to validate pending items first
Check if items were archived

Issue: Items stuck in 'processing' status

Solution:

Safety mechanism will timeout after 2 hours
Run timeoutStuckItems() function manually
Check for crashed/interrupted processor
Manually mark items as 'validated' to retry

Advanced Usage

Custom Agent Routing

Override automatic agent assignment:

import { updateQueueItem } from '@/lib/queue/work-queue-manager';

// Force specific agent
await updateQueueItem(itemId, {
  assigned_agent: 'rnd-tax-specialist',
  priority: 'P0',
});

Retry Failed Items

import { getQueueItemsByStatus, updateQueueItem } from '@/lib/queue/work-queue-manager';

// Get all failed items
const failedItems = await getQueueItemsByStatus('failed');

// Reset to validated for retry
for (const item of failedItems) {
  await updateQueueItem(item.id, {
    status: 'validated',
    error_message: null,
    error_count: 0,
  });
}

Bulk Archive Old Items

import { archiveOldFailedItems } from '@/lib/queue/work-queue-manager';

// Archive failed items older than 30 days
const archivedCount = await archiveOldFailedItems(30);
console.log(`Archived ${archivedCount} old failed items`);

Manual Timeout Cleanup

import { timeoutStuckItems } from '@/lib/queue/work-queue-manager';

// Timeout items stuck in 'processing' for > 2 hours
const timedOutCount = await timeoutStuckItems(2);
console.log(`Timed out ${timedOutCount} stuck items`);

Integration with Other Skills

Xero Integration

Queue items can trigger Xero data fetching:

// Example: R&D analysis queue item
const item = await addToQueue({
  title: 'Analyze R&D transactions for FY2023-24',
  description: 'Review all Xero transactions for R&D eligibility',
  queue_item_type: 'feature',
  payload: {
    financial_year: 'FY2023-24',
    start_date: '2023-07-01',
    end_date: '2024-06-30',
    analysis_type: 'rnd',
  },
});

// Processing will route to rnd-tax-specialist
// Agent will fetch Xero data automatically

Tax Law Research

Complex tax questions can be queued:

const item = await addToQueue({
  title: 'Research Division 7A loan repayment requirements',
  description: 'Client has $150K shareholder loan, need repayment schedule',
  queue_item_type: 'client_request',
  payload: {
    loan_amount: 150000,
    client_id: 'client-123',
    legislation: 'Division 7A ITAA 1936',
  },
});

// Processing will route to loss-recovery-agent
// Agent will research legislation and calculate repayments

Linear Workflow Integration

Queue items automatically sync with Linear:

Capture: Creates placeholder for future Linear issue
Validation: Creates Linear issue if not duplicate
Processing: Updates Linear issue status as work progresses
Completion: Marks Linear issue as complete, adds final comment

Reporting Integration

Queue data can feed into reports:

import { getQueueStatistics } from '@/lib/queue/work-queue-manager';
import { calculateValidationStats } from '@/lib/queue/pm-validator';

// Generate weekly report
const stats = await getQueueStatistics();
const validationStats = calculateValidationStats(validatedItems);

const report = {
  week: getCurrentWeek(),
  items_processed: stats.complete_count,
  success_rate: (stats.complete_count / (stats.complete_count + stats.failed_count) * 100),
  avg_execution_time: stats.avg_execution_time_seconds,
  by_complexity: validationStats.by_complexity,
  by_priority: validationStats.by_priority,
};

// Save to reports table or send to stakeholders

Future Enhancements

Planned Features

Priority Bumping: Auto-bump priority based on age or Linear updates
Scheduled Processing: Run processor at specific times (cron-like)
Batch Linear Updates: Reduce API calls by batching updates
Smart Retry Logic: Auto-retry failed items with exponential backoff
User Notifications: Notify when high-priority items complete
Analytics Dashboard: Web UI for queue statistics and trends
Agent Performance Metrics: Track success rate per agent
Complexity Prediction: ML model to predict execution time
Parallel Processing: Process multiple simple items in parallel
Queue Templates: Pre-defined templates for common workflows

Experimental Ideas

Voice Capture: Capture ideas via voice commands
Email Integration: Capture ideas from email
Slack Integration: Capture ideas from Slack messages
GitHub Integration: Capture ideas from GitHub issues/PRs
Auto-Prioritization: ML-based priority assignment
Cost Estimation: Estimate financial value of queue items

Changelog

v2.0.0 (2026-01-29)

Initial comprehensive skill documentation
Unified /workflow command interface
Integration with work-queue-manager.ts
Integration with pm-validator.ts
Integration with Linear API
Detailed examples for all commands
Error handling patterns
Performance targets and metrics
Testing checklist
Troubleshooting guide

References

Related Skills

idea-queue-capture - Fast idea capture (sub-skill)
work-queue-processor - Autonomous execution (sub-skill)
australian-tax-law-research - Tax legislation research
xero-api-integration - Xero data fetching
rnd-eligibility-assessment - R&D tax analysis

Related Files

lib/queue/work-queue-manager.ts - Queue operations
lib/queue/pm-validator.ts - Validation logic
lib/linear/api-client.ts - Linear integration
lib/linear/graphql-queries.ts - Linear utilities
lib/supabase/server.ts - Database client
supabase/migrations/20260129_create_work_queue.sql - Database schema

External Documentation

Linear API Documentation
Supabase JavaScript Client
Australian Tax Office (ATO)
Division 355 ITAA 1997 - R&D Tax Incentive

Notes

Designed for Australian Tax Optimizer (ATO) platform
Follows Matt Maher's "do-work" autonomous pattern
Complements "Capture Claude" and "Work Claude" two-instance pattern
Each item gets fresh sub-agent context (no pollution)
Observable via Linear for team visibility
Fault-tolerant: Continues on individual item failures
Archives maintain full audit trail
Uses Australian English throughout (optimisation, labour, etc.)

Last Updated: 2026-01-29 Version: 2.0.0 Author: Matt Maher Maintainer: Claude Code Agent Fleet

Agent Skills: Idea Intake Workflow - Unified Interface

Install this agent skill to your local

Skill Files