claude task workflow

create-claude-issue.md

name: create-claude-issue description: Create a detailed Linear issue optimized for Claude execution from high-level requirements version: 1.0

prompt: | You are creating Linear issues that will be executed by Claude (not humans). Follow this approach:

PHASE 1: GATHER HIGH-LEVEL REQUIREMENTS

Ask the user for these essential inputs only:

1. What do you want built/fixed/improved? (brief description)
2. What type of work is this? (Feature, Bug Fix, Refactor, Documentation, Analysis)
3. Which project/codebase area? (frontend, backend, api, database, etc.)
4. Any specific constraints or preferences? (technologies, approaches, deadlines)

PHASE 2: INTERNAL PLANNING & SPECIFICATION

Based on the user's input, YOU will internally plan and structure:

Technical Analysis:

• Break down the requirement into specific implementation steps
• Identify files/components that need changes
• Determine dependencies and prerequisites
• Plan testing approach and validation methods
• Consider edge cases and error handling

Complexity Assessment:

Score each factor 0-3 points to determine if issue should be split:

Factor	0 Points	1 Point	2 Points	3 Points
Code Volume	<50 LOC	50-200 LOC	200-500 LOC	>500 LOC
File Count	1-3 files	4-8 files	9-15 files	>15 files
Dependencies	None	Config only	New packages	Architecture change
Testing Needs	Unit only	+Integration	+E2E	+Performance
Risk Level	Isolated	Shared component	Core logic	Breaking changes

Total Score:

• 0-4: Simple (1-2 hours) - Single issue
• 5-9: Medium (2-6 hours) - Consider splitting
• 10+: Complex (6+ hours) - Must split into sub-issues

Claude-Optimized Structure:

Create detailed specifications that enable Claude to:

• Understand the full context immediately
• Execute without asking clarifying questions
• Validate completion against clear criteria
• Handle common issues and edge cases

PHASE 3: ISSUE SPECIFICATION TEMPLATE

Template Selection:

Based on the work type, consider using these project specific templates:

• Cloudflare Worker Endpoint: For new API endpoints
• SolidJS Component: For new UI components
• Durable Object: For stateful features with real-time sync
• WebSocket Handler: For new message types

Templates available in .claude/templates/

Title Format:

"[CLAUDE] [Action] [Component/Feature] - [Brief Description]" Examples:

• "[CLAUDE] Implement user authentication API endpoints"
• "[CLAUDE] Fix memory leak in data processing service"
• "[CLAUDE] Refactor database connection pooling"

Description Structure (Claude-Optimized):

## CLAUDE EXECUTION CONTEXT
**Work Type**: [Feature/Bug/Refactor/Documentation/Analysis]
**Estimated Complexity**: [Low/Medium/High] (Score: X/15)
**Estimated LOC**: [Approximate lines of code]
**File Count**: [Number of files to modify/create]
**Prerequisites**: [Any setup or dependencies needed]
**Technologies**: [Specific languages, frameworks, tools to use]

## OBJECTIVE
[Clear, single-sentence statement of what needs to be accomplished]

## DETAILED REQUIREMENTS
### Core Functionality:
- [Specific requirement 1 with technical details]
- [Specific requirement 2 with technical details]
- [Specific requirement 3 with technical details]

### Technical Specifications:
- **Input/Output**: [Expected inputs and outputs]
- **Performance**: [Any performance requirements]
- **Error Handling**: [How to handle edge cases and errors]
- **Integration Points**: [How this connects with existing systems]

## IMPLEMENTATION GUIDANCE
### Files/Components to Modify:
- `path/to/file1.js` - [What changes needed]
- `path/to/file2.py` - [What changes needed]
- `path/to/config.json` - [What changes needed]

### Step-by-Step Implementation:
1. [Specific implementation step with code context]
2. [Specific implementation step with code context]
3. [Specific implementation step with code context]

### Code Patterns to Follow:
- [Existing patterns in codebase to maintain consistency]
- [Naming conventions and style guidelines]
- [Architecture patterns to follow]

## VALIDATION CRITERIA
### Functional Tests:
- [ ] [Specific test case 1]
- [ ] [Specific test case 2]
- [ ] [Specific test case 3]

### Integration Tests:
- [ ] [Integration point 1 works correctly]
- [ ] [Integration point 2 works correctly]

### Edge Cases:
- [ ] [Edge case 1 handled properly]
- [ ] [Edge case 2 handled properly]

## SUCCESS METRICS
- [Measurable outcome 1]
- [Measurable outcome 2]
- [Performance benchmarks if applicable]

## IMPLEMENTATION READINESS CHECKLIST
- [ ] All file paths specified with exact locations
- [ ] Error handling approach documented
- [ ] Testing strategy defined (unit/integration/e2e)
- [ ] Performance requirements stated
- [ ] Rollback procedure included for risky changes
- [ ] Dependencies and prerequisites clearly listed
- [ ] Acceptance criteria are measurable
- [ ] Common {{ project }} patterns referenced

## CLAUDE EXECUTION NOTES
- **Autonomous Execution**: This issue contains all context needed for completion
- **No Clarification Needed**: All requirements and constraints are specified
- **Self-Validation**: Use the validation criteria to confirm completion
- **Error Recovery**: [Specific guidance for common issues that might arise]
- **Pattern References**: Link to {{ project }}-patterns.md for common implementations

PHASE 4: CONFIRMATION & CREATION

Before creating the Linear issue:

1. Present the planned issue to the user with:

   • The title you've generated
   • A summary of your technical analysis
   • Key implementation points
   • The full specification you'll include

2. Ask for confirmation: "Does this specification capture what you want? Should I create this Linear issue for Claude to execute?"

3. Allow refinements: Let the user request changes before creation

4. Create via MCP with proper:

   • Labels: ["claude-executable", work-type, component-area, priority]
   • Project: Default to "{{ put your project name here }}" project (ID: {{ project id here }})
   • Priority level based on urgency/impact

CLAUDE-SPECIFIC OPTIMIZATIONS

Information Density:

• Include all context Claude needs upfront
• Specify exact file paths and code locations
• Provide complete technical requirements
• Include relevant code patterns and examples

Execution Clarity:

• Break down complex tasks into clear steps
• Specify validation methods Claude can perform
• Include error handling and edge case guidance
• Provide clear success criteria

Autonomous Operation:

• Eliminate need for clarifying questions
• Include all constraints and preferences
• Specify testing and validation approaches
• Provide rollback procedures if needed

Code Context:

• Reference existing code patterns to follow
• Specify integration points and dependencies
• Include performance and quality requirements
• Provide examples of similar implementations

EXAMPLE INTERACTION FLOW:

User: "I need a REST API endpoint for user profile updates"

Claude Planning (Internal):

• Analyze existing API structure
• Plan endpoint design (/api/users/:id/profile)
• Consider validation, auth, error handling
• Plan database integration
• Design response format

Claude Response: "I'll create a comprehensive Linear issue for building a user profile update API endpoint. Based on your codebase, I'm planning:

• REST endpoint at /api/users/:id/profile (PUT method)
• Integration with existing auth middleware
• Validation using your current schema patterns
• Database updates with transaction safety
• Proper error responses and logging

This will be a Medium complexity issue that includes all implementation details, file locations, and validation criteria. Should I create this Linear issue for Claude to execute?"

After Confirmation: Create the Linear issue via MCP with full specification.

Remember: The goal is creating issues so comprehensive that Claude can execute them autonomously while maintaining high code quality and proper integration with existing systems.

implement-claude-issue.md

name: implement-linear-issue description: Retrieve and implement a Linear issue with incremental development and quality gates version: 2.0

Implement Linear issues following {{ project }} development practices

prompt: | You are implementing a Linear issue for the {{ project name }} project. Follow the project's established patterns and practices defined in CLAUDE.md files.

PHASE 1: ISSUE RETRIEVAL & SETUP

Step 1: Get Issue Details

1. Ask user for the Linear issue ID or URL
2. Retrieve issue via Linear MCP integration
   • If MCP unavailable: Ask user to paste issue details including title, description, and acceptance criteria
3. Extract key information:
   • Title and description
   • Acceptance criteria / success conditions
   • Priority and labels
   • Related issues or dependencies
   • Technical specifications

Step 2: Git Worktree Setup

Set up isolated development environment immediately after getting issue details:

# Create worktree with descriptive branch name
ISSUE_ID="[ISSUE-ID]"
BRANCH_NAME="feature/${ISSUE_ID}-[brief-kebab-case-description]"
WORKTREE_PATH=".trees/worktree-${ISSUE_ID}"

git worktree add "${WORKTREE_PATH}" -b "${BRANCH_NAME}"
cd "${WORKTREE_PATH}"

# Initial commit
git commit --allow-empty -m "feat: initialize ${ISSUE_ID} implementation

Objective: [One line description]

Setting up isolated worktree for development."

# Install dependencies in worktree
npm install

# Verify setup
git status
npm run typecheck
npm run build

Step 3: Pre-Implementation Validation

Before starting implementation, verify the issue is ready:

echo "🔍 Validating issue readiness..."

# Check for required information
MISSING_INFO=()

# Extract issue details and check each requirement
if [[ -z "$(grep -E 'Files?(/| )to(/| )(Modify|Create)' <<< "$ISSUE_CONTENT")" ]]; then
  MISSING_INFO+=("❌ No file paths specified")
fi

if [[ -z "$(grep -E '(Error|Exception|Result)(/| )(Handling|Recovery)' <<< "$ISSUE_CONTENT")" ]]; then
  MISSING_INFO+=("❌ Error handling approach not documented")
fi

if [[ -z "$(grep -E '(Test|Testing|Validation)(/| )(Strategy|Approach|Criteria)' <<< "$ISSUE_CONTENT")" ]]; then
  MISSING_INFO+=("❌ Testing strategy not defined")
fi

if [[ -z "$(grep -E '(Acceptance|Success)(/| )Criteria' <<< "$ISSUE_CONTENT")" ]]; then
  MISSING_INFO+=("❌ No measurable acceptance criteria")
fi

if [[ ${#MISSING_INFO[@]} -gt 0 ]]; then
  echo "⚠️  Issue is missing required information:"
  printf '%s\n' "${MISSING_INFO[@]}"
  echo ""
  echo "This issue may not be ready for autonomous implementation."
  echo "Consider updating the issue with missing information."
  read -p "Continue anyway? (y/n): " CONTINUE
  if [[ "$CONTINUE" != "y" ]]; then
    exit 1
  fi
else
  echo "✅ Issue contains all required implementation details"
fi

Step 4: Complexity Assessment

Score each factor 0-3 points:

Factor	0 Points	1 Point	2 Points	3 Points
Code Volume	<50 LOC	50-200 LOC	200-500 LOC	>500 LOC
File Count	1-3 files	4-8 files	9-15 files	>15 files
Dependencies	None	Config only	New packages	Architecture change
Testing Needs	Unit only	+Integration	+E2E	+Performance
Risk Level	Isolated	Shared component	Core logic	Breaking changes

Total Score:

• 0-4: Simple (1-2 hours)
• 5-9: Medium (2-6 hours)
• 10+: Complex (6+ hours)

If Complex: Ask user: "This issue appears complex. Should I break it into smaller sub-issues for better tracking?"

PHASE 2: PLANNING

Step 5: Create Implementation Plan

Generate and present this plan to the user:

## IMPLEMENTATION PLAN: [ISSUE-ID]

**Objective**: [Brief summary from Linear issue]
**Complexity**: [Simple/Medium/Complex] (Score: X/15)
**Estimated Duration**: [Time estimate]

### Technical Approach:

[2-3 sentences describing the solution approach]

### Files to Modify/Create:

- `src/[client|server]/[domain]/[file].ts` - [What changes and why]
- `src/[client|server]/[domain]/[file].test.ts` - [Unit tests]
- `tests/e2e/[feature].spec.ts` - [E2E tests if UI changes]

### Implementation Milestones:

1. **Setup & Types** (20%)

   - Define interfaces/types (server: Result types, client: signals)
   - Set up file structure following domain organization
   - Checkpoint: Type safety established

2. **Core Logic** (40%)

   - Implement main functionality
   - Server: Result-based error handling, no exceptions
   - Client: Reactive patterns, accessibility features
   - Checkpoint: Feature works in happy path

3. **Testing** (30%)

   - Write Vitest tests (AAA pattern, no mocks)
   - Add E2E tests if UI changes
   - Checkpoint: All tests passing

4. **Polish & Validation** (10%)
   - Verify against acceptance criteria
   - Performance optimization
   - Checkpoint: Ready for review

Proceed with implementation? (y/n)

PHASE 2.5: WORKTREE VALIDATION

Step 6: Verify Worktree Environment

Before proceeding with implementation, validate we're working in the correct isolated environment:

# Verify we're in a worktree
if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
  echo "❌ Not in a git repository"
  exit 1
fi

# Check if we're in a worktree (not main working directory)
if [[ "$(git rev-parse --show-toplevel)" == "$(pwd)" ]] && [[ ! -f ".git/worktrees" ]]; then
  echo "⚠️  WARNING: You appear to be working directly on main branch!"
  echo "This violates the isolated development workflow."
  echo "Current directory: $(pwd)"
  echo "Current branch: $(git branch --show-current)"
  read -p "Continue anyway? This is NOT recommended. (y/n): " CONTINUE
  if [[ "$CONTINUE" != "y" ]]; then
    echo "Please set up a worktree using Step 2 before proceeding."
    exit 1
  fi
else
  echo "✅ Working in isolated worktree environment"
  echo "Branch: $(git branch --show-current)"
  echo "Path: $(pwd)"
fi

# Verify dependencies are installed
if [[ ! -d "node_modules" ]]; then
  echo "❌ Dependencies not installed in worktree"
  echo "Running: npm install"
  npm install
fi

echo "✅ Worktree environment validated"

PHASE 3: INCREMENTAL IMPLEMENTATION

Core Development Loop

For each milestone, follow this cycle:

A. Implement Changes

• Follow project's CLAUDE.md guidelines for client/server code
• Make minimal, focused changes
• One logical unit at a time
• Keep changes reviewable (<100 lines per iteration)

B. Run Quality Checks

# Run all quality checks
echo "🔍 Running quality checks..."

# ESLint
npm run lint && echo "✅ ESLint passed" || echo "❌ ESLint failed"

# Prettier
npm run prettier  && echo "✅ Prettier passed" || echo "❌ Prettier failed"

# TypeScript compilation
npm run typecheck && echo "✅ TypeScript passed" || echo "❌ TypeScript failed"

# Vitest unit tests
npm run test:unit && echo "✅ Unit tests passed" || echo "❌ Unit tests failed"

# Playwright E2E tests (if UI changes exist)
if [[ -f "tests/e2e/${ISSUE_ID}*.spec.ts" ]]; then
  npm run test:e2e -- --grep "${ISSUE_ID}" && echo "✅ E2E tests passed" || echo "❌ E2E tests failed"
fi

# Build verification
npm run build && echo "✅ Build passed" || echo "❌ Build failed"

C. Handle Check Failures

If checks fail after 3 fix attempts, ask user for guidance with specific error details.

D. Create Checkpoint Commit

After ALL checks pass:

# Stage changes
git add -A

# Create conventional commit
git commit -m "[type]: [description under 50 chars]

- [Specific change 1]
- [Specific change 2]

Milestone: [X/4] - [Milestone name]
Quality: ✅ eslint ✅ prettier  ✅ typescript ✅ vitest ✅ build"

E. Progress Report

✅ MILESTONE [X/4] COMPLETED

**Milestone**: [Name]
**Changes Made**:

- [Key change 1]
- [Key change 2]

**Files Modified**: X files changed, Y insertions(+), Z deletions(-)
**Commit**: `[hash]` - "[commit message first line]"
**All Checks**: ✅ Passing

**Next**: [Next milestone description]

F. Update Linear Issue

After each milestone, update the Linear issue with progress:

# Create progress comment in Linear
LINEAR_COMMENT="### 🚀 Milestone [X/4] Complete: [Milestone Name]

**Progress**: [X*25]% complete
**Time Elapsed**: [Duration since start]

**Changes Made**:
- [Key accomplishment]
- Files modified: [count]
- Tests added: [count]

**Quality Checks**:
- ✅ ESLint: Clean
- ✅ Prettier: Clean
- ✅ TypeScript: Passing
- ✅ Tests: All passing
- ✅ Build: Successful

**Next Steps**: [Next milestone description]"

# Use Linear MCP to add comment (if available)
# Or ask user to update Linear manually

PHASE 4: VALIDATION & COMPLETION

Step 7: Comprehensive Validation

# Run full test suite
npm run test:unit

# Run E2E tests if applicable
npm run test:e2e

# Final quality check
npm run prettier && npm run lint && npm run typecheck && npm run build

Step 8: Manual Testing Checklist

## Manual Validation

Linear Issue Acceptance Criteria:

- [ ] [Criterion 1 from Linear issue]
- [ ] [Criterion 2 from Linear issue]
- [ ] [Criterion 3 from Linear issue]

All quality checks passing:

- [ ] ESLint clean
- [ ] TypeScript compilation successful
- [ ] Prettier
- [ ] Tests passing
- [ ] Build successful

Step 9: Final Implementation Commit

git commit -m "feat: complete implementation of ${ISSUE_ID}

✅ All acceptance criteria met
✅ TypeScript strict mode passing
✅ Unit test coverage: X%
✅ E2E tests passing
✅ ESLint clean
✅ Prettier

Summary:
- [Key accomplishment 1]
- [Key accomplishment 2]
- [Key accomplishment 3]

Ready for review and merge."

PHASE 5: MERGE & CLEANUP

Step 10: Pre-merge Checks

# Ensure all tests pass one final time
npm prettier && npm run lint && npm run typecheck && npm run test:unit && npm run test:e2e

# Update from main
git checkout main
git pull origin main
git checkout ${BRANCH_NAME}
git rebase main

# If conflicts, resolve and continue
# git rebase --continue

Step 11: Merge Process

# Return to main worktree
cd [original-project-path]

# Merge feature branch
git checkout main
git merge --no-ff ${BRANCH_NAME}

# Push changes
git push origin main

Step 12: Cleanup

# Remove worktree
git worktree remove "${WORKTREE_PATH}"

# Delete feature branch
git branch -d ${BRANCH_NAME}
git push origin --delete ${BRANCH_NAME}

# Prune worktree references
git worktree prune

Step 13: Update Linear Issue

## ✅ IMPLEMENTATION COMPLETE

**Branch**: `[branch-name]` → merged to main
**Commits**: [number] commits
**Files Changed**: [number] files, +[additions] -[deletions]

**Key Changes**:

- [Summary of major change 1]
- [Summary of major change 2]
- [Summary of major change 3]

**Quality Metrics**:

- ✅ ESLint: 0 errors, 0 warnings
- ✅ TypeScript: Compilation successful
- ✅ Build: Successful
- ✅ All tests passing

**Acceptance Criteria Validation**:

- ✅ [Criterion 1]: [How it was met]
- ✅ [Criterion 2]: [How it was met]
- ✅ [Criterion 3]: [How it was met]

**Deployment Ready**: Yes

Trying this more minimal command to reduce context rot

name: implement-linear-issue
description: Streamlined Linear issue implementation with worktree isolation and local quality checks
version: 2.1

prompt: |
You are implementing a Linear issue for the {{ project }} project. Follow the project's established patterns and practices defined in CLAUDE.md files.

PHASE 1: SETUP

Step 1: Get Issue Details

1. Ask user for the Linear issue ID or URL
2. Retrieve issue via Linear MCP integration
   • If MCP unavailable: Ask user to paste issue details
3. Extract: title, description, and acceptance criteria

Step 2: Git Worktree Setup

# Create worktree
ISSUE_ID="[ISSUE-ID]"
BRANCH_NAME="feature/${ISSUE_ID}-[brief-description]"
WORKTREE_PATH=".trees/worktree-${ISSUE_ID}"

git worktree add "${WORKTREE_PATH}" -b "${BRANCH_NAME}"
cd "${WORKTREE_PATH}"
npm install

# Initial commit
git commit --allow-empty -m "feat: initialize ${ISSUE_ID} implementation"

PHASE 2: PLANNING

Step 3: Create Implementation Plan

## IMPLEMENTATION PLAN: [ISSUE-ID]

**Objective**: [Brief summary from Linear issue]

### Files to Modify/Create:
- `src/[client|server]/[domain]/[file].ts` - [What changes]
- `src/[client|server]/[domain]/[file].test.ts` - [Tests]

### Implementation Steps:
1. **Setup & Types** - Define interfaces/types
2. **Core Logic** - Implement functionality with Result patterns
3. **Testing** - Write Vitest tests
4. **Validation** - Verify acceptance criteria

Proceed? (y/n)

PHASE 3: IMPLEMENTATION

Development Loop

For each step:

A. Implement Changes

• Follow CLAUDE.md guidelines
• Make focused, reviewable changes
• One logical unit at a time

B. Quality Checks

npm run prettier && npm run lint && npm run typecheck && npx vitest run && npm run build

C. Commit

git add -A
git commit -m "[type]: [description]

- [Key change]

Step [X/4] complete"

PHASE 4: COMPLETION

Step 4: Final Validation

# Final quality check
npm run prettier && npm run lint && npm run typecheck && npx vitest run && npm run build

Step 5: Final Commit

git commit -m "feat: complete ${ISSUE_ID} implementation

✅ All acceptance criteria met
✅ All quality checks passing

Ready for review."

PHASE 5: PR & CLEANUP

Step 6: Push & Create PR

# Push branch
git push origin ${BRANCH_NAME}

Ask user to:

1. Create GitHub PR from the pushed branch
2. Review and merge via GitHub UI
3. Confirm when merged

Step 7: Post-merge Cleanup

After user confirms merge:

# Return to main worktree
cd [original-project-path]

# Update main
git checkout main && git pull origin main

# Remove worktree and branch
git worktree remove "${WORKTREE_PATH}"
git branch -d ${BRANCH_NAME}
git push origin --delete ${BRANCH_NAME}
git worktree prune

delete all my project