> ## Documentation Index > Fetch the complete documentation index at: https://docs.namastex.ai/llms.txt > Use this file to discover all available pages before exploring further. # Creating Tasks > Learn how to create and configure tasks in Forge ## Overview Tasks are the core unit of work in Forge. Each task represents a specific piece of work to be executed by AI coding agents in isolated environments. *** ## Creating Your First Task ### Via Web UI ```bash theme={null} forge start # Opens http://localhost:3000 ``` Click the **+ New Task** button in the Kanban board * **Title**: Clear, concise description * **Description**: Detailed requirements and context * **LLM**: Choose your AI agent (Claude, Gemini, etc.) * **Labels**: Add tags for organization Click **Create** - your task appears in the "To Do" column ### Via CLI ```bash theme={null} # Basic task creation forge task create \ --title "Add user authentication" \ --description "Implement JWT-based auth with login and signup" \ --llm claude # With additional options forge task create \ --title "Refactor API client" \ --description "Convert fetch calls to axios" \ --llm gemini \ --priority high \ --labels "refactor,backend" \ --assignee "claude" ``` ### Via MCP (from your coding agent) ``` You: "Create a task to add dark mode toggle with LocalStorage persistence" Claude Code: I'll create that task for you... [Uses MCP create_task tool] Task created: #42 "Add dark mode toggle" ``` *** ## Task Properties ### Required Fields Clear, action-oriented title **Good**: "Add JWT authentication endpoints" **Bad**: "Auth stuff" ```bash theme={null} forge task create --title "Add JWT authentication endpoints" ``` Detailed requirements, context, and acceptance criteria ```bash theme={null} forge task create \ --title "Add authentication" \ --description " Implement JWT-based authentication with: - POST /auth/login endpoint - POST /auth/signup endpoint - JWT token generation with 24h expiry - Password hashing with bcrypt - Input validation - Error handling " ``` ### Optional Fields AI coding agent to use Options: `claude`, `gemini`, `cursor`, `openai`, `opencode`, `qwen` ```bash theme={null} forge task create --title "Quick fix" --llm gemini ``` Task priority: `low`, `medium`, `high`, `critical` ```bash theme={null} forge task create --title "Security patch" --priority critical ``` Tags for organization and filtering ```bash theme={null} forge task create \ --title "Add tests" \ --labels "testing,backend,priority:high" ``` Specific agent profile or team member ```bash theme={null} forge task create --title "Security audit" --assignee "security-expert" ``` *** ## Task Types & Templates ### Feature Development ```bash theme={null} forge task create \ --title "Add export to CSV functionality" \ --type feature \ --description " Create CSV export feature: - Add download button to UI - Implement CSV generation logic - Handle large datasets (stream) - Add progress indicator - Include proper filename with timestamp " \ --labels "feature,ui,backend" ``` ### Bug Fix ```bash theme={null} forge task create \ --title "Fix memory leak in WebSocket connection" \ --type bugfix \ --priority high \ --description " Steps to reproduce: 1. Connect to WebSocket 2. Leave page open for 1 hour 3. Memory usage grows continuously Expected: Stable memory usage Actual: Memory grows by ~50MB/hour Stack trace: [attach if available] " \ --labels "bug,websocket,critical" ``` ### Refactoring ```bash theme={null} forge task create \ --title "Extract API client to separate module" \ --type refactor \ --description " Current state: API calls scattered across components Goal: Centralized API client with: - Axios instance with interceptors - Error handling middleware - Retry logic for failed requests - TypeScript types for all endpoints " \ --labels "refactor,architecture" ``` ### Documentation ```bash theme={null} forge task create \ --title "Document authentication flow" \ --type docs \ --description " Create comprehensive docs for: - How JWT tokens are generated - Token refresh flow - Password reset process - OAuth integration Include sequence diagrams " \ --labels "docs,auth" ``` ### Testing ```bash theme={null} forge task create \ --title "Add integration tests for payment flow" \ --type testing \ --description " Test scenarios: - Successful payment - Failed payment (card declined) - Network timeout during payment - Webhook handling - Refund flow Use Jest + Supertest Aim for 90%+ coverage " \ --labels "testing,payment" ``` *** ## Writing Effective Task Descriptions ### Bad Description ❌ ``` Add user stuff to the dashboard ``` ### Good Description ✅ ```markdown theme={null} ## Goal Add user management section to admin dashboard ## Requirements - Display paginated user list (20 per page) - Show: name, email, registration date, status - Add filters: status (active/inactive), role - Implement search by name or email - Add "Edit User" modal with: - Change role (user/admin) - Toggle active status - Reset password option ## Technical Notes - Use existing UserService API - Match design system components - Add loading states and error handling - Include unit tests for filtering logic ## Acceptance Criteria - [ ] User list loads and paginates correctly - [ ] Filters work as expected - [ ] Search returns accurate results - [ ] Edit modal saves changes successfully - [ ] All edge cases handled (empty state, API errors) ``` ### Tips for Great Descriptions **Bad**: "Make it faster" **Good**: "Reduce API response time from 2s to under 500ms by adding Redis caching" Why is this needed? What problem does it solve? "Users complain about slow dashboard load times. Profiling shows 80% time spent in database queries." Add acceptance criteria: * [ ] Dashboard loads in under 1 second * [ ] Cache hit rate over 70% * [ ] Tests pass Include: * Design mockups * API documentation * Similar implementations * Stack traces (for bugs) *** ## Task Organization ### Using Labels ```bash theme={null} # Category labels --labels "feature,bug,docs,refactor,testing" # Priority labels --labels "priority:high,priority:low" # Component labels --labels "frontend,backend,database,auth" # Status labels --labels "blocked,in-review,needs-testing" # Team labels --labels "team:mobile,team:api" # Combine multiple --labels "feature,backend,priority:high,team:api" ``` ### Filtering Tasks ```bash theme={null} # By label forge task list --labels "feature" forge task list --labels "priority:high" # By status forge task list --status pending forge task list --status in_progress # By assignee forge task list --assignee claude # Combine filters forge task list --labels "bug" --priority high --status pending ``` *** ## Attaching Context ### Code Snippets ```bash theme={null} forge task create \ --title "Optimize database query" \ --description " Current slow query: \`\`\`sql SELECT * FROM users WHERE created_at > NOW() - INTERVAL 30 DAY \`\`\` Takes 5 seconds on 1M users. Add index on created_at. " ``` ### Screenshots (Web UI) 1. Click **Attach Files** in task creation modal 2. Upload screenshots, diagrams, or mockups 3. Reference in description: "See attached mockup.png" ### Links ```markdown theme={null} ## References - Design: https://figma.com/file/xyz - API Docs: https://docs.example.com/api - Similar feature: https://github.com/user/repo/pull/123 ``` *** ## Advanced: Task Dependencies ```bash theme={null} # Create parent task forge task create \ --title "Build payment system" \ --id parent-task # Create dependent tasks forge task create \ --title "Stripe integration" \ --depends-on parent-task forge task create \ --title "Payment UI components" \ --depends-on parent-task forge task create \ --title "Webhook handling" \ --depends-on parent-task ``` Tasks with dependencies are blocked until parent completes. *** ## Batch Task Creation ### From File Create `tasks.yaml`: ```yaml theme={null} tasks: - title: "Setup database schema" description: "Create tables for users, posts, comments" priority: high labels: ["database", "setup"] - title: "Create API endpoints" description: "CRUD operations for posts" labels: ["backend", "api"] - title: "Build frontend components" description: "Post list, create post form" labels: ["frontend", "ui"] ``` Import: ```bash theme={null} forge task import tasks.yaml ``` ### Programmatic Creation ```typescript theme={null} import { ForgeClient } from 'automagik-forge-sdk'; const forge = new ForgeClient(); const tasks = [ { title: "Task 1", description: "..." }, { title: "Task 2", description: "..." }, { title: "Task 3", description: "..." }, ]; for (const task of tasks) { await forge.createTask(task); } ``` *** ## Best Practices **Bad**: "Build entire e-commerce platform" **Good**: "Add product listing page" Smaller tasks = better AI results **Bad**: "Add auth and refactor database" **Good**: Two separate tasks Focus improves quality Define done: * [ ] Feature works as described * [ ] Tests pass * [ ] Documentation updated Show, don't just tell: ```javascript theme={null} // Expected usage: const token = await auth.generateToken(user); ``` *** ## Troubleshooting **Error**: "Failed to create task" **Solutions**: * Check project is selected * Verify database is accessible * Ensure title is not empty * Check LLM is configured **Issue**: Task created but not visible **Solutions**: * Refresh the Kanban board * Check filters aren't hiding it * Use search: `forge task list --search "your title"` **Issue**: Same task created multiple times **Solutions**: * Check for button double-clicks * Use unique IDs if programmatic * Search before creating: `forge task list --search "similar"` *** ## Next Steps Run tasks with different AI agents Compare outputs from multiple agents Reusable patterns for common workflows Complete CLI command reference