source .agent/linear-api.sh
linear_check_connection

[TYPE]: Brief, actionable description

## Overview

**Problem Statement:** [Clear description of what's broken or missing]

**Why This Matters:** [Business/technical justification - user impact, revenue, technical debt]

**Current State:** [How things work now, including limitations]

**Desired State:** [How things should work after implementation]

---

## Requirements

### Requirement 1: [Core Functionality Title]

**User Story:** As a [role], I want [goal], so that [benefit].

#### Acceptance Criteria

1. WHEN [trigger] THE System SHALL [action]
2. IF [condition] THEN THE System SHALL [response]
3. THE System SHALL [always-on requirement]
4. THE [Component] SHALL [render/display/update] [specific behavior]
5. WHEN [error scenario] THE System SHALL [error handling behavior]

### Requirement 2: Error Handling

**User Story:** As a user, I want clear error messages, so that I can understand and recover from problems.

#### Acceptance Criteria

1. WHEN [error occurs] THE System SHALL [display user-friendly message]
2. THE System SHALL [log error to Sentry with category tag]
3. THE System SHALL [preserve user data/state despite error]

### Requirement 3: Performance

**User Story:** As a user, I want fast response, so that my workflow isn't interrupted.

#### Acceptance Criteria

1. THE System SHALL [complete operation in <X seconds]
2. THE System SHALL [show loading state after 200ms]

---

## Design

### Architecture

[Component hierarchy, data flow diagram]

### Key Files

- `path/to/file1.tsx` - [what changes]
- `path/to/file2.py` - [what changes]

### Data Models

```typescript
interface NewFeatureData {
  id: string;
  userId: string;
  // ... relevant fields
}

## Quick Issue Format

For simple tasks, create a lightweight GitHub Issue:

### Title Format

### Body Format

```markdown
**PURPOSE:** What needs to be done and why (1-2 sentences)

**KEY FILES:** (if known)
- path/to/likely/file.tsx

**ACCEPTANCE CRITERIA:**
- [ ] Clear, testable criterion 1
- [ ] Clear, testable criterion 2
- [ ] Clear, testable criterion 3

SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)/../.."
source "$SCRIPT_DIR/.agent/config.sh"
source "$SCRIPT_DIR/.agent/linear-api.sh"

# Linear workspace IDs for consuelo
export LINEAR_TEAM_ID="29f5c661-da6c-4bfb-bd48-815a006ccaac"
export LINEAR_LABEL_CLAUDE_ID="b3c52ecf-d35a-4ccd-a305-c288f033c01f"

# Default project: Suelo (use unless user explicitly specifies another)
export LINEAR_PROJECT_SUELO_ID="10004248-b69d-4a76-825a-83d5628571c8"

# Other projects (only use when explicitly requested)
export LINEAR_PROJECT_MERCURY_ID="10004248-b69d-4a76-825a-83d5628571c8"

# Determine which project to use (default: Suelo)
PROJECT_ID="${LINEAR_PROJECT_SUELO_ID}"

# Check if user explicitly requested a different project
if [[ "$USER_REQUEST" == *"mercury"* ]] || [[ "$USER_REQUEST" == *"Mercury"* ]]; then
  PROJECT_ID="${LINEAR_PROJECT_MERCURY_ID}"
elif [[ "$USER_REQUEST" == *"in the"*"project"* ]] || [[ "$USER_REQUEST" == *"put this in"* ]]; then
  # Extract project name from request - default remains Suelo unless explicitly changed
  : # Keep Suelo as default
fi

# Check for --priority flag in user's request
PRIORITY=0  # Default: no priority

if [[ "$USER_REQUEST" == *"--priority urgent"* ]]; then
  PRIORITY=1
elif [[ "$USER_REQUEST" == *"--priority high"* ]]; then
  PRIORITY=2
elif [[ "$USER_REQUEST" == *"--priority medium"* ]]; then
  PRIORITY=3
elif [[ "$USER_REQUEST" == *"--priority low"* ]]; then
  PRIORITY=4
fi

# Build issue body (Full Spec or Quick Issue format)
ISSUE_BODY=$(cat <<'EOF'
[Full spec or quick issue markdown content here]
EOF
)

# Create Linear issue (uses PROJECT_ID which defaults to Suelo)
RESULT=$(curl -s -X POST https://api.linear.app/graphql \
  -H "Authorization: $LINEAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"query\": \"mutation IssueCreate(\$input: IssueCreateInput!) { issueCreate(input: \$input) { success issue { id identifier title url } } }\",
    \"variables\": {
      \"input\": {
        \"title\": \"[TYPE]: Title here\",
        \"description\": \"$ISSUE_BODY\",
        \"teamId\": \"$LINEAR_TEAM_ID\",
        \"projectId\": \"$PROJECT_ID\",
        \"labelIds\": [\"$LINEAR_LABEL_CLAUDE_ID\"],
        \"priority\": $PRIORITY
      }
    }
  }")

# Check for success
if ! echo "$RESULT" | jq -e '.data.issueCreate.success' > /dev/null 2>&1; then
  echo "ERROR: Failed to create Linear issue"
  echo "$RESULT" | jq '.errors'
  exit 1
fi

# Extract issue details
ISSUE_ID=$(echo "$RESULT" | jq -r '.data.issueCreate.issue.id')
ISSUE_IDENTIFIER=$(echo "$RESULT" | jq -r '.data.issueCreate.issue.identifier')
ISSUE_URL=$(echo "$RESULT" | jq -r '.data.issueCreate.issue.url')

Created Linear issue DEV-456 (Full Spec, Priority: High)

Title: [FEATURE]: Implement user authentication with email/password and Google OAuth
Added to Suelo project

View: https://linear.app/your-workspace/issue/DEV-456

Key acceptance criteria:
- Email/password account creation with validation
- Google OAuth integration
- Email verification flow
- Rate limiting on failed logins
- Comprehensive error handling

The agent will pick this up automatically from Linear.

Title: [DOC]: Executive Planning — <Initiative Name>

Body:
## Context & Vision

[What problem are we solving? What's the thesis? Capture the strategic thinking.]

## Key Decisions

[Decisions made during planning — pricing model, tech choices, target users, etc.]

## Architecture Overview

[High-level view of what's being built and how pieces fit together]

## Task Map

[List all related task identifiers with brief descriptions — serves as an index]

## Open Questions

[Anything unresolved that future sessions should address]

## Conversation Summary

[Condensed version of the brainstorming that led to these tasks — capture the reasoning, not just the output]

# Check Linear API connection
source .agent/linear-api.sh
linear_check_connection

# View ready issues in Linear
source .agent/linear-api.sh
linear_get_ready_issues

# Get Linear label and project IDs (one-time setup)
source .agent/linear-api.sh
linear_setup_cache

# View team info
source .agent/linear-api.sh
linear_get_teams

# View workflow states
source .agent/linear-api.sh
linear_get_team_states "$LINEAR_TEAM_ID"

# View team labels
source .agent/linear-api.sh
linear_get_team_labels "$LINEAR_TEAM_ID"

# Run the agent workflow (Linear mode)
.agent/run-tasks.sh --source linear

# Preview Linear issues without processing
.agent/run-tasks.sh --source linear --dry-run

# Open Linear workspace in browser
open "https://linear.app/your-workspace"