npm package: @openpets/asana
Description: Asana plugin for OpenCode - manage tasks, projects, and boards with full CRUD operations
Latest version: 1.0.7

# Asana Plugin for OpenCode

A comprehensive Asana integration plugin for OpenCode that enables full task and project management capabilities through natural language commands.

## Core APIs Used

- **Asana REST API v1.0** - Primary API for all Asana operations
- **Authentication**: Personal Access Token (PAT) authentication
- **Base URL**: `https://app.asana.com/api/1.0`

## Setup Instructions

### 1. Generate Asana Personal Access Token

**Step-by-step instructions:**

1. **Log in to Asana**
   - Go to [https://app.asana.com](https://app.asana.com)
   - Sign in with your Asana account

2. **Access Developer Settings**
   - Click your profile picture in the top right corner
   - Select **"My Apps"** from the dropdown menu
   - Or navigate directly to: [https://app.asana.com/0/my-apps](https://app.asana.com/0/my-apps)

3. **Create Personal Access Token**
   - Click the **"+ New personal access token"** button
   - Enter a descriptive name (e.g., "OpenCode Integration")
   - Click **"Create"**
   - **Important**: Copy the token immediately - you won't be able to see it again

4. **Set Environment Variable**
   ```bash
   # For Unix/macOS/Linux
   export ASANA_ACCESS_TOKEN="your-token-here"
   
   # For Windows (PowerShell)
   $env:ASANA_ACCESS_TOKEN="your-token-here"
   
   # For Windows (Command Prompt)
   set ASANA_ACCESS_TOKEN=your-token-here
   ```

5. **Permanent Setup**
   Add the environment variable to your shell profile (`~/.bashrc`, `~/.zshrc`, etc.) or create a `.env` file:
   ```env
   ASANA_ACCESS_TOKEN=your-token-here
   ```

### 2. Required Permissions

The Personal Access Token needs these permissions:
- View tasks, projects, and workspaces
- Create and edit tasks
- Add comments and attachments
- Manage projects and sections
- Read user information

**Note**: Personal Access Tokens inherit the permissions of the user who created them.

### 3. Test Connection

After setting up the token, test the connection:

```bash
opencode run "Test Asana connection and return user details"
```

## Key Concepts

### GIDs (Global IDs)
Asana uses GIDs (Global IDs) as unique identifiers for all resources:
- Workspaces have GIDs
- Projects have GIDs  
- Tasks have GIDs
- Users have GIDs
- Sections (columns) have GIDs

**How to find GIDs:**
- Look at the URL when viewing items in Asana web app
- Use the list/get tools to retrieve them programmatically

### Workspaces vs Projects
- **Workspace**: Top-level organization (company/team)
- **Project**: Container for tasks within a workspace
- **Section**: Columns within projects (for board view)

## Available Commands

### Connection & Discovery
- `asana-test-connection` - Test API connection and get user info
- `asana-get-workspaces` - List all accessible workspaces
- `asana-get-projects` - List projects in a workspace
- `asana-get-users` - Get users in a workspace

### Project Management
- `asana-get-project` - Get project details
- `asana-get-project-sections` - List project sections/columns
- `asana-create-section` - Create new section in project

### Task Operations
- `asana-get-tasks` - Get tasks from project
- `asana-get-section-tasks` - Get tasks from specific section
- `asana-get-task` - Get detailed task information
- `asana-create-task` - Create new task
- `asana-update-task` - Update existing task
- `asana-move-task-to-section` - Move task between columns
- `asana-delete-task` - Delete a task

### Task Management
- `asana-get-subtasks` - Get subtasks of a task
- `asana-create-subtask` - Create subtask
- `asana-add-comment` - Add comment to task
- `asana-get-task-stories` - Get task activity/comments

### Search & Filtering
- `asana-search-tasks` - Search tasks in workspace
- `asana-get-my-tasks` - Get tasks assigned to current user

### Tags & Followers
- `asana-get-tags` - Get tags in workspace
- `asana-add-tag-to-task` - Add tag to task
- `asana-remove-tag-from-task` - Remove tag from task
- `asana-add-follower-to-task` - Add follower to task

## Usage Examples

### Basic Workflow
```bash
# 1. Test connection
opencode run "Test Asana connection and return user details"

# 2. List workspaces
opencode run "List all workspaces accessible to the authenticated user"

# 3. Get projects from workspace
opencode run "List all projects in workspace 123456789"

# 4. Get tasks from project
opencode run "Get tasks from project 987654321"
```

### Task Management
```bash
# Create a task
opencode run "Create a new task in project 987654321 with name 'Review documentation' and notes 'Check API documentation for accuracy'"

# Move task to Done section
opencode run "Move task 555555555 to section 777777777"

# Add comment
opencode run "Add comment 'Documentation review completed successfully' to task 555555555"
```

### Search Operations
```bash
# Search for specific tasks
opencode run "Search for tasks in workspace 123456789 with text 'urgent'"

# Get my tasks
opencode run "Get tasks assigned to the current user in workspace 123456789"
```

## Environment Variables

### Required
- `ASANA_ACCESS_TOKEN` - Personal Access Token from Asana Developer Console

### Optional
No optional environment variables currently supported.

## Troubleshooting

### Common Issues

1. **"Plugin not configured" error**
   - Ensure `ASANA_ACCESS_TOKEN` is set correctly
   - Test the token with: `opencode run "Test Asana connection"`

2. **"Invalid token" error**
   - Verify the token wasn't revoked
   - Check for typos in the token
   - Create a new token if needed

3. **"Access denied" errors**
   - Verify the user has permission to access the requested resources
   - Check if the project/workspace GIDs are correct

4. **Rate limiting**
   - Asana has rate limits - wait a moment between requests
   - The plugin automatically handles rate limiting with retries

### Debugging
Enable debug logging by setting:
```bash
export DEBUG=asana-plugin
```

### Finding GIDs
Use these commands to find resource GIDs:
```bash
# Get workspace GIDs
opencode run "List all workspaces accessible to the authenticated user"

# Get project GIDs from workspace
opencode run "List all projects in workspace YOUR_WORKSPACE_GID"

# Get section GIDs from project
opencode run "Get all sections in project YOUR_PROJECT_GID"
```

## Security Best Practices

1. **Token Security**
   - Never commit tokens to version control
   - Use environment variables, not hardcoded values
   - Rotate tokens regularly
   - Use descriptive names for tokens to track usage

2. **Permissions**
   - Only grant necessary permissions
   - Regularly review token access
   - Delete unused tokens

3. **Access Control**
   - Use service accounts for integrations when possible
   - Limit token scope to specific workspaces if needed

## API Limits

- **Rate Limit**: Approximately 150 requests per minute
- **Pagination**: Large datasets are automatically paginated
- **Field Selection**: Only requested fields are returned to optimize bandwidth

## Support

- **Asana API Documentation**: [https://developers.asana.com/docs](https://developers.asana.com/docs)
- **Personal Access Tokens**: [https://developers.asana.com/docs/personal-access-tokens](https://developers.asana.com/docs/personal-access-tokens)
- **Rate Limits**: [https://developers.asana.com/docs/rate-limits](https://developers.asana.com/docs/rate-limits)

## Version History

- **v1.0.1** - Current version with full Asana API integration
- **v1.0.0** - Initial release

## Contributing

This plugin follows OpenPets standards. See the [OpenPets Development Guide](../AGENTS.md) for development guidelines.