Task Connector Extension

A Cursor/VSCode extension that scans documentation folders for task information, generates comprehensive task documentation using Claude Sonnet LLM, and uploads tasks directly to ClickUp and other project management tools.

Features

• Task ID Detection: Automatically finds tasks marked with Task ID: <ID> in documentation files
• AI-Powered Documentation: Uses Claude Sonnet LLM to generate comprehensive task documentation
• ClickUp Integration: Automatically uploads generated tasks to ClickUp
• Smart Upload Tracking: Upload tasks once or use [Force] tag for repeated uploads
• Architecture Diagrams: Use [Image] tag to generate Mermaid diagrams automatically
• Output Channel: View AI-generated task documentation in a dedicated output panel
• Manual Scanning: Trigger scans manually or preview AI-generated content
• Connection Testing: Test Claude and ClickUp API connections

🚀 Supercharge Your Workflow with AI Coding Assistants

Maximize the benefit of Task Connector by integrating it with your AI coding assistant (like Cursor, GitHub Copilot, or others). Create a seamless workflow where your AI assistant generates task documentation files, and Task Connector automatically processes and uploads them to your project management tool.

Recommended Setup for Cursor

Add these rules to your Cursor AI configuration (.cursorrules file in your project root or Cursor settings):

- always go through all the '.md' files in 'documentation' folder to understand project context and dont use emojis on those documents.
- create the '.md' documents in the 'documentation' folder in the root folder.

Recommended Setup for Other AI Assistants

Configure your AI assistant with similar rules:

1. Create documentation in a dedicated folder (e.g., documentation/, docs/, tasks/)
2. Use markdown format (.md files)
3. Include Task IDs at the top of each file (e.g., Task ID: FEAT-123)
4. Avoid emojis in task documentation for better compatibility with project management tools

Example Workflow

1. Ask your AI assistant to create a task:

   • "Create a task for implementing user authentication in the documentation folder"

2. AI creates a file (e.g., documentation/user-auth.md):

   Task ID: AUTH-001
   
   # User Authentication Implementation
   
   Implement secure user authentication system...
   

3. Task Connector processes it:

   • Run: Cmd/Ctrl + Shift + P → "Scan Documentation Folder"
   • Task Connector generates comprehensive documentation using Claude
   • Automatically uploads to ClickUp with all details

4. Result: Task appears in ClickUp with full documentation, architecture diagrams, and acceptance criteria!

Benefits of This Integration

✅ No manual task creation - AI generates structured task files
✅ Consistent format - All tasks follow the same template
✅ Automatic context - AI reads existing tasks to maintain consistency
✅ One-click sync - Single command uploads everything to ClickUp
✅ Version control - Task documentation is tracked in Git

Installation

1. Clone or download this extension
2. Open the extension in Cursor/VSCode
3. Press F5 to run the extension in a new Extension Development Host window
4. Or package the extension and install the .vsix file

Configuration

Settings

Configure the extension through Cursor/VSCode settings:

1. Open Settings (Cmd/Ctrl + ,)
2. Search for "Task Connector"
3. Configure the following settings:

taskConnector.documentationDirectory

• Type: String
• Default: ""
• Description: Absolute path to the directory containing your documentation files (MD files)
• Example: /Users/username/Projects/MyProject/docs
• ⚠️ IMPORTANT: Set this in Workspace Settings (not User Settings) so each project has its own path

How to Configure Per-Project (Recommended Method):

1. Open your project folder in VS Code
2. Press Cmd/Ctrl + Shift + P to open Command Palette
3. Run: "Task Connector: Set Documentation Directory (Workspace)"
4. The command will show your workspace path (e.g., /Users/username/Projects/MyProject)
5. Enter a relative path like docs or documentation, OR an absolute path
6. The extension automatically validates the directory exists
7. ✅ Done! Settings are saved in .vscode/settings.json for this project only

Example:

• Workspace path shown: /Users/username/Projects/MyProject
• You type: docs
• Extension saves to settings.json: "taskConnector.documentationDirectory": "docs"
• 💡 Benefit: Relative paths can be committed to Git and work for all team members!

Team Collaboration:

When you use relative paths (recommended):

• ✅ Commit .vscode/settings.json to version control
• ✅ All team members get the same configuration automatically
• ✅ No need to manually configure on each machine
• ✅ Works regardless of where the project is cloned

Alternative: Via Settings GUI

If you prefer using the Settings GUI:

1. Press Cmd/Ctrl + , to open Settings
2. Click the "Workspace" tab (not "User") at the top
3. Search for "Task Connector"
4. Set the "Documentation Directory" (must be absolute path)

Important Notes:

• User Settings: Global across all projects (❌ Don't use for documentation path)
• Workspace Settings: Per-project settings (✅ Use this for documentation path)
• Each project can have a different documentation directory

API Keys (Secure Storage)

API keys are now stored securely using VS Code's built-in secure storage mechanism. Use the following commands to set them:

• Claude API Key: Set via Task Connector: Set Claude API Key command
• ClickUp API Key: Set via Task Connector: Set ClickUp API Key command
• ClickUp Configuration: Set via Task Connector: Set ClickUp Configuration command
• Clear All Keys: Use Task Connector: Clear All API Keys command

taskConnector.clickupTaskIdType

• Type: String (enum)
• Default: "native"
• Options: "native" or "custom"
• Description: Type of task IDs used in your ClickUp workspace
  • native: ClickUp-generated IDs (e.g., 86bnz7vkr)
  • custom: Custom task IDs (e.g., PROJ-123)

taskConnector.createTasksIfNotFound

• Type: Boolean
• Default: false (disabled)
• Description: Controls whether to create new tasks in ClickUp when the task ID is not found
  • Disabled (default): Only existing tasks will be updated. If a task ID is not found, an error is reported and the task is skipped.
  • Enabled: New tasks will be created automatically in ClickUp if they don't exist.

Recommended Usage:

• Keep this disabled if you want to only update existing ClickUp tasks
• Enable this if you're creating tasks from scratch and want them automatically created in ClickUp
• Use custom task IDs in your documentation to match existing ClickUp task IDs

Template Configuration (Command)

• Access: Run Task Connector: Configure Template from Command Palette
• Description: Visual drag-and-drop interface to configure template sections
• Security: Uses structured sections to prevent prompt injection attacks

Usage

Documenting Tasks

Important: Each markdown file should contain only ONE task. The Task ID must be at the very top of the file.

In your markdown files, use the following format:

Task ID: FEAT-123

# Feature Implementation

This task involves implementing a new user authentication system.
The implementation should include login, logout, and session management.

Additional details about the implementation...

## Technical Requirements

- Use JWT tokens for session management
- Implement bcrypt for password hashing

## Testing Requirements

- Unit tests for all authentication flows
- Integration tests for OAuth providers

Optional Tags (place immediately after Task ID):

• Add [Force] to upload this task every scan (instead of just once)
• Add [Image] to generate a Mermaid architecture diagram
• You can use both tags together (see Special Tags section below)

Special Tags

Force Upload Tag - [Force]

By default, tasks are only uploaded once. After a successful upload, the extension tracks uploaded task IDs and skips them in subsequent scans. To force a task to be uploaded every time you scan, add the [Force] tag:

Task ID: FEAT-123
[Force]

# Feature Implementation

This task will be uploaded every time you run a scan, even if it was already uploaded before.

Formatting Requirements:

• ✅ Must be exactly [Force] (capital F, lowercase o-r-c-e)
• ✅ Must be on its own line immediately after Task ID: (within first 2 lines)
• ✅ No extra spaces: [Force] not [ Force ] or [Force ]
• ✅ Nothing else on that line: [Force] not [Force] - update this

Use Cases for [Force] Tag:

• Tasks that need frequent updates
• Tasks where you want to sync changes from documentation to ClickUp
• Testing and development

Upload History Management:

• View upload history: Automatically tracked in workspace state
• Clear upload history: Use Task Connector: Clear Upload History command
• After clearing history, all non-forced tasks will be uploaded again on next scan

Image/Diagram Tag - [Image]

To include an architecture diagram in your task documentation, add the [Image] tag. Claude will automatically generate a Mermaid diagram:

Task ID: FEAT-123
[Image]

# Feature Implementation

Implement a new microservices architecture...

Formatting Requirements:

• ✅ Must be exactly [Image] (capital I, lowercase m-a-g-e)
• ✅ Must be on its own line immediately after Task ID: (within first 2 lines)
• ✅ No extra spaces: [Image] not [ Image ] or [Image ]
• ✅ Works with or without [Force] tag (see below)

Using Both Tags Together

You can use both [Force] and [Image] tags together. Place them on separate lines immediately after the Task ID (order doesn't matter):

Task ID: FEAT-123
[Force]
[Image]

# Feature Implementation

This task will be uploaded every scan AND include an architecture diagram.

OR

Task ID: FEAT-123
[Image]
[Force]

# Feature Implementation

Both orders work - the extension checks the first 2 lines after the Task ID.

Important Formatting Rules:

• ✅ Tags must be exactly [Force] or [Image] (case-sensitive)
• ✅ Tags must be on their own line
• ✅ Tags must appear within the first 2 lines after Task ID:
• ✅ No spaces inside brackets: [Force] not [ Force ]
• ❌ Don't add extra text on the tag line: [Force] - update this won't work

Note: The [Force] tag is for internal tracking only and won't appear in the generated documentation sent to ClickUp. The [Image] tag instructs Claude to generate a Mermaid architecture diagram

Commands

Access commands through the Command Palette (Cmd/Ctrl + Shift + P):

• Task Connector: Set Documentation Directory (Workspace) - ⭐ Set the documentation path for THIS project only
• Task Connector: Scan Documentation Folder - Manually scan for tasks and process with Claude
• Task Connector: Preview Task with Claude - Preview AI-generated task documentation
• Task Connector: Test Claude Connection - Test Claude API connectivity
• Task Connector: Test ClickUp Connection - Test ClickUp API connectivity
• Task Connector: Set Claude API Key - Securely set Claude API key
• Task Connector: Set ClickUp API Key - Securely set ClickUp API key
• Task Connector: Set ClickUp Configuration - Set ClickUp Team ID and List ID
• Task Connector: Clear All API Keys - Clear all stored API keys
• Task Connector: Clear Upload History - Reset task upload tracking (tasks will be uploaded again)
• Task Connector: Configure Template - Open visual template configurator with drag-and-drop
• Task Connector: Open Task Connector Settings - Quick access to settings

Template Configuration

Customize your task documentation sections using the visual configurator:

1. Open the Configurator:

   • Open Command Palette (Cmd/Ctrl + Shift + P)
   • Run Task Connector: Configure Template
   • A visual editor will open with drag-and-drop interface

2. Customize Sections:

   • ☑ Check/uncheck to enable/disable sections
   • 🖱️ Drag sections to reorder using the handle
   • ✏️ Edit section names and descriptions
   • ➕ Add custom sections
   • 🗑️ Delete custom sections

3. Default Sections Available:

   • Context - Why this task is needed, its purpose, and related dependencies
   • Architecture Diagram - Mermaid diagrams for visual architecture (when [Image] tag present)
   • Implementation Details / Design Spec - Technical approach and solution outline
   • Acceptance Criteria - Minimum requirements for task completion
   • How to Test - Testing procedures and validation steps
   • Non-functional requirements - Performance, security, scalability considerations
   • Risks for implementing this feature - Potential challenges and mitigation strategies

4. Security Benefits:

   • 🔒 Structured sections prevent prompt injection attacks
   • ✅ No free-form text input that could override AI instructions
   • 🛡️ Content is sanitized and sandboxed before being sent to Claude

API Setup Requirements

Claude API Key Setup

1. Get your API key from Anthropic Console
2. Open Command Palette (Cmd/Ctrl + Shift + P)
3. Run Task Connector: Set Claude API Key
4. Enter your API key (starts with sk-ant-)
5. Security: Keys are stored in VS Code's secure storage, encrypted and protected

ClickUp API Setup

1. Get API Key:

   • Go to ClickUp Settings → Apps → API
   • Copy your API key (starts with pk_)
   • Run Task Connector: Set ClickUp API Key command

2. Get Team ID:

   • Open your ClickUp workspace
   • Look at the URL: https://app.clickup.com/12345678/home
   • The Team ID is 12345678

3. Get List ID:

   • Navigate to the specific list where tasks should be created
   • Right-click on the List name in the left sidebar
   • Select "Copy Link" from the context menu
   • The URL will look like: https://app.clickup.com/12345678/v/l/87654321
   • ⚠️ Important: Don't copy the URL from the address bar - always use "Copy Link"

4. Configure:

   • Run Task Connector: Set ClickUp Configuration command
   • Paste the copied List URL when prompted
   • The extension will automatically extract Team ID and List ID

Security

API Key Security

• ✅ Secure Storage: API keys are stored in VS Code's encrypted secure storage, not in the extension code
• ✅ OS-Level Encryption: Keys are encrypted using your operating system's keychain/credential store
• ✅ No Hardcoding: No API keys or secrets are embedded in the source code
• ✅ User-Specific: Each user must configure their own API keys
• ✅ Password Input: Keys are entered via secure password input fields
• ✅ Validation: Input validation ensures proper key format before storage

Best Practices

1. Never commit API keys to version control
2. Use environment variables for development if needed
3. Rotate API keys regularly
4. Use least-privilege access - create API keys with minimal required permissions
5. Monitor API usage through your provider's dashboard

Extension Security

• The extension code contains no sensitive information
• API keys are loaded at runtime from VS Code's encrypted secure storage
• All API calls use HTTPS encryption
• No data is stored permanently by the extension

How It Works

1. File Monitoring: The extension watches the configured documentation directory for changes
2. Task Detection: When files are created or modified, the extension looks for Task ID: <ID> at the top of each file
3. Content Extraction: Extracts all content after the Task ID line (entire file content minus the Task ID line)
4. AI Processing: Sends the raw task content to Claude Sonnet LLM for comprehensive documentation generation
5. ClickUp Upload: Automatically uploads the AI-generated task documentation to your ClickUp workspace
6. Real-time Feedback: Shows progress and results in the "Task Connector" output channel with notifications

Development

Building the Extension

1. Install dependencies:

   npm install
   

2. Compile TypeScript:

   npm run compile
   

3. Run in development mode:

   npm run watch
   

4. Package the extension:

   npx vsce package
   

Project Structure

src/
├── extension.ts          # Main extension entry point
├── fileWatcher.ts        # File system monitoring
├── taskParser.ts         # Task ID extraction and parsing
└── templateFormatter.ts  # Template formatting logic

Troubleshooting

Common Issues

1. No tasks found: Ensure your markdown files contain Task ID: <ID> at the very top of the file
2. File watcher not working: Check that the documentation directory path is correct and accessible
3. Template not formatting: Verify your template has proper section headers in brackets
4. Multiple tasks in one file: Remember: one file = one task. Split multiple tasks into separate files

Debug Information

Enable debug logging by opening the Developer Console (Help > Toggle Developer Tools) to see extension logs.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Support

For issues and feature requests, please contact the development team. [zameerm@99x.io]