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:

typescript

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:

typescript

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:

typescript

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:

typescript

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:

typescript

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:

typescript

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:

typescript

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:

typescript

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:

typescript

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:

bash

# 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:

typescript

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

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

Retry Failed Items

typescript

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

typescript

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

typescript

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:

typescript

// 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:

typescript

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:

typescript

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

idea-intake-workflow

NPX Install

Tags

SKILL.md Content

Idea Intake Workflow - Unified Interface

Purpose

Philosophy

Quick Start Guide

For First-Time Users

Common Workflows

Commands

/workflow (no args)

/workflow capture

/workflow validate

/workflow process

/workflow status

/workflow stats

Implementation Notes

Architecture Overview

Key Dependencies

Data Flow

Error Handling Patterns

Configuration

Security Considerations

Performance Optimization

Testing Checklist

Capture Tests

Validation Tests

Processing Tests

Status Tests

Stats Tests

Troubleshooting

Common Issues

Advanced Usage

Custom Agent Routing

Retry Failed Items

Bulk Archive Old Items

Manual Timeout Cleanup

Integration with Other Skills

Xero Integration

Tax Law Research

Linear Workflow Integration

Reporting Integration

Future Enhancements

Planned Features

Experimental Ideas

Changelog

v2.0.0 (2026-01-29)

References

Related Skills

Related Files

External Documentation

Notes

`/workflow`
(no args)

`/workflow capture`

`/workflow validate`

`/workflow process`

`/workflow status`

`/workflow stats`