implement-task

name	implement-task
description	Implement a complete Plane epic by reading tasks, understanding dependencies, and coding sequentially. Use when working on a full epic or multi-task feature.

/implement-task - Implement Plane Epic End-to-End

Use this skill to implement a complete task from Plane. This workflow reads the epic, analyzes dependencies between subtasks, implements them sequentially, and opens a PR when done.

Usage

/implement-task <EPIC-ID>

Example: /implement-task BETON-42 or /implement-task INSP-15

Workflow

Do not assume my priorities on timeline or scale. After each section, pause and ask for my feedback before moving on.

BEFORE YOU START: Ask if I want one of two options: 1/ BIG CHANGE: Work through this interactively, one section at a time (Architecture → Code Quality → Tests → Performance) with at most 4 top issues in each section. 2/ SMALL CHANGE: Work through interactively ONE question per review section FOR EACH STAGE OF REVIEW: output the explanation and pros and cons of each stage's questions AND your opinionated recommendation and why, and then use AskUserQuestion make sure each option clearly labels the issue NUMBER and option LETTER as the user doesn't get confused. Make the recommended option always the 1st option. LETTER as the user doesn't get confused. Make the recommended option always the 1st option.

My engineering preferences (use these to guide your recommendations):

DRY is important—flag repetition aggressively. Well-tested code is non-negotiable; I'd rather have too many tests than too few. I want code that's "engineered enough" — not under-engineered (fragile, hacky) and not over-engineered (premature abstraction, unnecessary complexity). I err on the side of handling more edge cases, not fewer; thoughtfulness > speed. Bias toward explicit over clever.

Phase 1: Work Item Discovery

Step 1.1: Fetch the Epic

Use the Plane MCP tools to read the epic:

mcp__plane__retrieve_work_item_by_identifier:
  - project_identifier: <PROJECT> (e.g., "BETON", "INSP")
  - sequence_id: <NUMBER> (e.g., "42")

Read and note:

• Task title and description
• Acceptance criteria
• Any attachments or linked resources

Step 1.2: Get All Subtasks

List subtasks that belong to this epic using the parent_id filter (primary approach):

mcp__plane__list_work_items:
  - project_id: <uuid from epic>
  - parent_id: <task/epic uuid>

If list_work_items with parent_id doesn't return results, fall back to searching:

mcp__plane__search_work_items:
  - project_id: <uuid from epic>
  - search: <epic name or related keywords>

Or if the epic has linked issues, fetch each one:

mcp__plane__retrieve_work_item_by_identifier for each subtask

Step 1.3: Read Attachments

If the epic or subtasks have descriptions with links, requirements docs, or Figma designs:

• Use WebFetch or related MCP o read linked documents
• Note key requirements, API specs, or design decisions

Step 1.4: Identify Dependencies

Analyze the subtasks for:

• Blockers: Tasks that must complete before others can start
• Shared code: Tasks that modify the same files
• Data dependencies: Tasks where output feeds into another

Create a dependency order. Example:

1. BETON-43: Add database migration (no deps)
2. BETON-44: Create API endpoint (depends on migration)
3. BETON-45: Add frontend form (depends on API)
4. BETON-46: Add tests (depends on all above)

Step 1.5: Plan review

Review this plan thoroughly before making any code changes. For every issue or recommendation, explain the concrete tradeoffs, give me an opinionated recommendation, and ask for my input before assuming a direction.

Evaluate:

Overall system design and component boundaries. Dependency graph and coupling concerns. Data flow patterns and potential bottlenecks. Scaling characteristics and single points of failure. Security architecture (auth, data access, API boundaries).

---

Phase 2: Branch Setup

⛔ CRITICAL: DO NOT CREATE SUPABASE DATABASE BRANCHES

Never use mcp__supabase__create_branch or create new database branches. Google OAuth clients are configured for specific Supabase projects - creating a new DB branch will break authentication entirely. All feature branches use the existing staging database.

Step 2.1: Fetch Latest Staging

git fetch origin staging

Step 2.2: Create Feature Branch (Git Only)

Branch naming: feature/<task-id>-<short-name>

git checkout -b feature/<EPIC-ID>-<epic-short-name> origin/staging

Example:

git checkout -b feature/BETON-42-user-dashboard origin/staging

Then, publish the branch

git push origin feature/<EPIC-ID>-<epic-short-name>

---

Phase 3: Sequential Implementation

For EACH task in dependency order:

Step 3.1: Read the Task

Fetch full task details:

mcp__plane__retrieve_work_item_by_identifier

Understand:

• What exactly needs to be built
• Acceptance criteria
• Edge cases mentioned

Step 3.2: Ask Clarifying Questions

If anything is unclear, use AskUserQuestion to clarify:

• Architecture decisions
• UI/UX specifics not in the task
• Error handling requirements
• Integration points

Do NOT proceed with assumptions if the task is ambiguous.

Step 3.3: Implement the Code

Change task status to "In progress" in Plane.

Write the code following Beton's patterns:

• API Routes: Place in src/app/api/
• Pages: Place in src/app/(dashboard)/
• Components: Place in src/components/
• Business Logic: Place in src/lib/
• Signal Detectors: Place in src/lib/heuristics/signals/detectors/
• Integration Clients: Place in src/lib/integrations/
• Supabase Migrations: Place in supabase/migrations/

Follow existing patterns in the codebase.

Evaluate:

Code organization and module structure. DRY violations—be aggressive here. Error handling patterns and missing edge cases (call these out explicitly). Technical debt hotspots. Areas that are over-engineered or under-engineered relative to my preferences.

Step 3.4: Build Locally

MANDATORY before committing:

npm run build

If build fails:

1. Read the error messages carefully
2. Fix TypeScript errors
3. Fix import issues
4. Re-run build until it passes

Do NOT commit code that fails the build.

Step 3.5: Test the Implementation

Evaluate:

Test coverage gaps (unit, integration, e2e). Test quality and assertion strength. Missing edge case coverage—be thorough. Untested failure modes and error paths. N+1 queries and database access patterns. Memory-usage concerns. Caching opportunities. Slow or high-complexity code paths.

For API endpoints:

Test with curl to verify the endpoint works:

# Example: Test a GET endpoint
curl -s http://localhost:3000/api/<endpoint> | jq

# Example: Test a POST endpoint
curl -X POST http://localhost:3000/api/<endpoint> \
  -H "Content-Type: application/json" \
  -d '{"field": "value"}' | jq

Verify:

• Response status is correct (200, 201, etc.)
• Response body matches expected schema
• Error cases return proper error responses

For UI components:

• Verify the page loads without errors in browser. Use Chrome Extension MCP for this
• Check browser console for errors
• Test key user interactions

For each issue you find: For every specific issue (bug, smell, design concern, or risk):

Describe the problem concretely, with file and line references. Present 2-3 options, including "do nothing" where that's reasonable. For each option, clearly: implementation effort, risk, impact on other code, and maintenance burden. Give me your recommended option and why, mapped to my preferences above. Then explicitly ask whether I agree or want to choose a different direction before proceeding.

Step 3.6: Commit

Use the /deploy skill workflow to:

• Stage and commit the changes for this task

Commit message should reference the task ID and provide a URL:

feat(<scope>): <task description>

Implements [<TASK-ID>: <task title>](task_url)

Co-Authored-By: Claude Opus 4.5 <[e-mail]>

Step 3.7: Repeat for Next Task

Move to the next task in dependency order and repeat Steps 3.1-3.6.

---

Phase 4: Pull Request

Once ALL tasks are complete, push the branch to origin. Then:

Step 4.1: Final Build Check

npm run build

Ensure entire branch builds cleanly.

Step 4.2: Create Draft Pull Request

Use the /deploy skill's "Feature → Staging" workflow to:

• Verify Vercel preview deployment
• Create PR to staging branch
• Include all completed task IDs in the PR body

PR body should include:

## Summary
Implements epic <EPIC-ID>: <Epic title>

### Tasks Completed
- [x] <TASK-1>: <description>
- [x] <TASK-2>: <description>
- [x] <TASK-3>: <description>

## Test Plan
- [ ] Verified locally with `npm run build`
- [ ] Tested API endpoints with curl
- [ ] Checked UI in browser

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Step 4.3: Generate Product Documentation

IMPORTANT: After creating the PR, use the /document-task skill to generate comprehensive product documentation:

/document-task <EPIC-ID>

This should happen automatically after you've created a draft PR. Then, attach a page with documentation to the PR + link it to the epic.

Step 4.4: Report Completion

Tell the user:

• PR URL
• Summary of what was implemented
• Documentation page created in Plane wiki
• Any follow-up items or notes for review

STOP HERE - Do NOT merge the PR. Beton engineers will review and merge manually.

---

Checklist

• Read epic and all subtasks from Plane
• Identified dependency order
• Created feature branch from origin/staging
• For each task:
  • Read task details
  • Asked clarifying questions if needed
  • Implemented code
  • Tested with curl (if API)
  • Built locally (must pass)
  • Used /deploy to commit and push
• Created PR to staging (via /deploy)
• Generated documentation (via /document-task)
• Reported PR URL and documentation link to user
• Did NOT merge - left for human review

---

Common Patterns

Multi-tenant data access

Always filter by workspace:

const membership = await getWorkspaceMembership()
const { data } = await supabase
  .from('table')
  .select('*')
  .eq('workspace_id', membership.workspaceId)

API Route Authentication

import { createClient } from '@/lib/supabase/server'
import { getWorkspaceMembership } from '@/lib/supabase/helpers'
import { NextResponse } from 'next/server'

export async function GET() {
  const supabase = await createClient()
  const { data: { user } } = await supabase.auth.getUser()

  if (!user) {
    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
  }

  const membership = await getWorkspaceMembership()
  if (!membership) {
    return NextResponse.json({ error: 'No workspace' }, { status: 404 })
  }

  // ... rest of handler
}

Error Handling

try {
  // operation
} catch (error) {
  console.error('Operation failed:', error)
  return NextResponse.json(
    { error: 'Operation failed' },
    { status: 500 }
  )
}

---

Troubleshooting

Issue	Solution
Build fails	Read error, fix TypeScript issues
API returns 401	Check auth headers and Supabase client
Curl connection refused	Ensure npm run dev is running
Push rejected	Pull latest staging, resolve conflicts
Task unclear	Ask user with AskUserQuestion
RLS violation	Add .eq('workspace_id', ...) filter
Epic not found via MCP	Verify epics are enabled in project settings; use list_work_item_types to check for types with is_epic: true

---

Notes

• Do NOT skip the build step - CI will fail anyway
• Do NOT batch commits - commit after each task
• Do NOT proceed with assumptions - ask if unclear
• Do push frequently - saves progress, enables early feedback
• Do NOT merge PRs - only create them, leave merging to humans