AI Coding Assistant Integration

Learn how to integrate Lexicon5 with your AI coding assistant for powerful task management. This guide covers Claude Code, Windsurf, and other MCP-compatible tools.

Introduction

Lexicon5 integrates with AI coding assistants through skills and workflows that connect directly to your project management system. Whether you use Claude Code, Windsurf, or another MCP-compatible tool, the core functionality remains the same - only the folder structure differs.

With Lexicon5 integration, you can manage tasks, projects, and resources using natural language commands. The configuration package includes specialized skills/workflows that enable your AI assistant to create tasks, report bugs, implement features, and even run an autonomous project manager.

Same functionality, different folder structure: Claude Code uses .claude/skills/ while Windsurf uses .windsurf/workflows/. The capabilities are identical.

Prerequisites

Before setting up the integration, ensure you have:

  • An MCP-compatible AI coding assistant installed (Claude Code, Windsurf, etc.)
  • A Lexicon5 account with an active project
  • Node.js installed (for Claude Code's task-manager.mjs script)
# Claude Code installation
npm install -g @anthropic-ai/claude-code

# Windsurf - Download from codeium.com/windsurf

Setup

Follow these steps to configure your AI coding assistant with Lexicon5:

1

Select Your Project

In the Lexicon5 dashboard, use the project dropdown in the header to select the project you want to work with.

2

Generate API Key

Navigate to Project Settings by clicking on your project name. In the "View Details" tab, find the "API Keys" section and click "+ Generate Key".

Important: Copy your API key immediately after generation. It will not be shown again for security reasons.

3

Download Configuration Package

In the "Download Configuration Package" section of Project Settings, select your AI assistant tab (Claude Code or Windsurf) and click "Download ZIP".

4

Install Configuration

Extract the downloaded ZIP file to your project root. This creates the configuration folder with all necessary files.

# Extract to your project root
unzip lexicon5-config.zip -d /path/to/your/project

# Verify the installation
ls -la .claude/

Configuration Package

The downloaded ZIP contains a complete configuration structure. The folder name and internal structure varies by AI assistant, but the functionality is identical.

.claude/
├── skills/
│   ├── task-manager/
│   │   ├── .env              # Pre-configured credentials
│   │   ├── SKILL.md          # Skill documentation
│   │   ├── task-manager.mjs  # JavaScript script for API calls
│   │   ├── CLAUDE.md         # Project-level instructions
│   │   └── references/
│   │       ├── Task-Template.md
│   │       ├── Example-Task-(RPG).md
│   │       └── tools.md
│   ├── lexicon5-create-task/
│   │   └── SKILL.md
│   ├── lexicon5-implement-task/
│   │   └── SKILL.md
│   ├── lexicon5-issue-report/
│   │   └── SKILL.md
│   └── lexicon5-project-manager/
│       └── SKILL.md

Key difference: Claude Code uses skills stored in .claude/skills/ with a task-manager.mjs script for API calls.

Environment Variables

The configuration includes your project credentials (pre-filled when downloaded). For Claude Code, these are in .claude/skills/task-manager/.env. For Windsurf, they're in .windsurf/mcp.json.

API_KEY / x-api-key

Your generated API key for authentication

USER_ID / x-user-id

Your Lexicon5 user ID

ORGANIZATION_ID / x-organization-id

Your organization ID

PROJECT_ID / x-project-id

The selected project ID

Note: All values are automatically filled when you download the configuration package from the Lexicon5 dashboard. You do not need to manually configure these values.

Skills/Workflows Overview

The configuration package includes specialized skills (Claude Code) or workflows (Windsurf) that extend your AI assistant's capabilities for task management. These provide identical functionality across platforms.

Create Task

Create feature tasks with BDD acceptance criteria

Conducts discovery by asking clarifying questions, researches your codebase for patterns and conventions, then creates a comprehensive task with implementation-ready subtasks.

Issue Report

Report bugs with structured format

Researches your codebase to identify affected files, creates a structured bug report with reproduction steps, and applies appropriate tags.

Implement TaskInternal

Implement tasks from the task system

Retrieves task details, implements each subtask following BDD acceptance criteria, writes tests, and moves the task to QA status. Typically invoked by the project manager rather than directly.

Project Manager

Autonomous development loop (Claude Code only)

Continuously monitors for tasks in 'todo' status, spawns developer subagents to implement them, verifies test coverage, and manages the development cycle autonomously.

Command Reference

Claude Code

  • /lexicon5-create-task
  • /lexicon5-issue-report
  • /lexicon5-implement-task
  • /lexicon5-project-manager

Windsurf

  • /lexicon5-task-researcher
  • /lexicon5-qa-analyst
  • /lexicon5-developer

Creating Tasks

Simply describe what you need in natural language, and your AI assistant will create a comprehensive task with implementation-ready subtasks. The assistant asks clarifying questions to capture all requirements before creating the task.

Example Requests

  • "I need to add a user profile page with avatar upload"
  • "Create a task for implementing dark mode"
  • "Plan a feature for email notifications"

Conversation Flow

Creating a Task

U
I need to add a user profile page with avatar upload functionality
C
I'll create a task for this feature. Let me ask a few discovery questions first to ensure we capture all requirements:

1. Should users be able to crop their avatar before uploading?
2. What file formats should be supported (PNG, JPG, WebP)?
3. Is there a maximum file size limit?
U
Yes to cropping, support PNG and JPG, max 5MB
C
Perfect! I've researched your codebase and created a comprehensive task with BDD acceptance criteria:

task_xyz123: Add user profile page with avatar upload
- Subtask 1: Create profile page component
- Subtask 2: Implement avatar upload with cropping
- Subtask 3: Add file validation (PNG/JPG, 5MB max)
- Subtask 4: Update user API endpoints

Each subtask includes Given-When-Then scenarios for clear acceptance criteria.

Implementing Tasks

The developer workflow follows a structured approach: load context, implement code, verify with tests, and hand off to QA.

/lexicon5-implement-task / lexicon5-developer

Start implementing an existing task. The assistant retrieves task details, implements each subtask, runs verification, and moves the task to QA status when complete.

Example:

Implement task task_abc123

Implementation Workflow

  1. Load Context: Retrieves task details, subtasks, and implementation instructions
  2. Implement: Works through each subtask, following project patterns
  3. Verify: Runs pnpm lint and pnpm build to ensure quality
  4. Hand Off: Adds completion comment with test plan, moves task to QA status

Note: The developer workflow never marks tasks as "done" - it always moves them to "qa" status for verification. Only QA can mark tasks complete.

Reporting QA Issues

When you discover a bug, use the issue report command to create a structured bug task. The QA analyst researches your codebase to identify affected files and creates a comprehensive report.

/lexicon5-issue-report / lexicon5-qa-analyst

Report a bug or QA issue. The assistant researches your codebase, identifies affected files, and creates a structured bug task with the 'Bug' tag.

Example:

Report: Save button fails silently on mobile devices

What the QA Analyst Does

  • Researches your codebase to understand the affected area
  • Identifies specific files that may need modification
  • Creates a structured bug task with reproduction steps
  • Automatically applies the Bug tag
  • Includes technical context for developers

Project Manager (Autonomous Loop)

The autonomous project manager implements the Ralph Wiggum pattern - a continuous agentic loop that persists until all tasks are complete. It embodies "naive persistence" - it keeps trying until it succeeds.

Currently available for Claude Code only. The project manager skill requires subagent spawning capabilities.

How the Loop Works

  1. Scan: Queries for tasks with "todo" status only
  2. Spawn: Creates up to 2 developer subagents concurrently
  3. Implement: Each agent implements tasks following BDD criteria
  4. Verify: Checks test coverage and implementation completeness
  5. Resume: If verification fails, resumes the agent (up to 3 times)
  6. Repeat: Scans for more tasks and continues the loop

Example Output

Project Manager Output
[SCAN] Checking for tasks in todo status...
[FOUND] 3 tasks in todo status
[SPAWN] Starting agent for task_abc123: "Add user settings page"
[SPAWN] Starting agent for task_def456: "Fix API validation bug"
[VERIFY] task_def456 - checking test coverage...
[COMPLETE] task_def456 completed successfully
[SCAN] Checking for tasks in todo status...
[FOUND] 2 tasks in todo status
[SPAWN] Starting agent for task_ghi789: "Update dashboard layout"
[VERIFY] task_abc123 - checking test coverage...
[COMPLETE] task_abc123 completed successfully
[COMPLETE] task_ghi789 completed successfully
[SCAN] Checking for tasks in todo status...
[FOUND] 0 tasks in todo status
[IDLE] No tasks in todo status. Waiting for new work...

Note: The project manager runs continuously until stopped with Ctrl+C. This creates a hands-off development experience where you add tasks to the "todo" column and the loop implements them automatically.

Troubleshooting

Common issues and solutions:

Connection Failed

Verify your API key is correct and hasn't expired. Check that all required headers (API key, organization ID, project ID, user ID) are present in your configuration.

Tasks Not Loading

Ensure you have the correct project selected in Lexicon5. Verify the project ID in your configuration matches your intended project.

Skills/Workflows Not Recognized

Restart your AI assistant to reload the configuration. Check that the configuration files are in the correct location under your project root.

API Key Security Warning

Add your configuration folder to .gitignore to avoid committing API keys. For Windsurf, consider moving mcp.json outside the project directory.