Managing Tickets And Tasks In Plane

Managing Tickets and Tasks in Plane

Plane Configuration

Connection: Plane MCP server or direct Plane REST API via curl

Premium Features Limitation: Cycles (sprints) are a premium-only feature. Use sprint labels as a workaround:

• Create labels: sprint-1, sprint-2, sprint-3, etc.
• Filter views by sprint label to simulate cycle boards
• Use label colors to visually distinguish sprints (e.g., teal for current sprint)

Multi-Workspace Support: Automatically detects workspace from:

1. Local .plane.json in project root (highest priority)
2. Git remote URL patterns
3. Current directory path
4. PLANE_WORKSPACE environment variable
5. Default workspace from ~/.claude/plane-workspaces.json

Plane REST API Endpoints:

• GET /api/v1/workspaces/{workspace}/projects/{project}/issues/ - List issues
• POST /api/v1/workspaces/{workspace}/projects/{project}/issues/ - Create issue
• PATCH /api/v1/workspaces/{workspace}/projects/{project}/issues/{id}/ - Update issue
• GET /api/v1/workspaces/{workspace}/projects/{project}/states/ - List states/statuses
• GET /api/v1/workspaces/{workspace}/projects/{project}/labels/ - List labels

Authentication: X-Api-Key header with value from workspace-specific env var (e.g., PLANE_API_KEY)

Core Workflows

0. Initialize New Project (First-Time Setup)

When initializing a new project in Plane, execute the full onboarding workflow:

Trigger: "initialize project in plane", "setup plane for project", or first ticket creation in unknown project

Workflow Steps:

1. Create/Verify Project

   • Check if project exists (by identifier)
   • Create if missing with description from README/CLAUDE.md
   • Set project emoji based on theme

2. Generate Absurd Project Art (via fal-text-to-image skill)

   • Generate themed mascot/header image using project context
   • Prompt formula: "A weird [PROJECT_THEME] creature in absurdist corporate art style, [PROJECT_SPECIFIC_ELEMENTS], vibrant colors, slightly unsettling but friendly, like a mascot designed by a 5-year-old CEO"
   • Save to docs/[project]-mascot.png
   • Set as Plane project cover image

3. Create Label Taxonomy

   • Priority: must-have, should-have, could-have (MoSCoW)
   • Sprint: sprint-1, sprint-2, sprint-3, etc. (workaround for premium cycles)
   • Type: infrastructure, feature, ai-pipeline, auth, monetization
   • Effort: effort:S, effort:M, effort:L, effort:XL (optional)
   • Special: blocked, needs-review (status helpers)

4. Seed Backlog from PRD (if PRD exists)

   • Parse feature list from PRD
   • Create one ticket per feature with:
     • Description from PRD user story
     • Appropriate phase/priority/effort labels
     • Acceptance criteria from PRD

5. Establish Art Theme (document in project)

   • Create docs/PLANE_ART_THEME.md with:
     • Theme name and visual language
     • Tone description
     • Usage guidelines for ticket categories
     • Original mascot prompt for variations

Output:

✓ Project initialized: [PROJ] Project Name
  Cover: docs/project-mascot.png (uploaded)
  Labels: 14 created (3 priority, 4 phase, 4 effort, 3 type)
  Backlog: 10 tickets seeded from PRD
  Art Theme: "Theme Name" documented in docs/PLANE_ART_THEME.md

See references/project-initialization.md for detailed workflow.

1. Create Ticket from Story/Task

Parse input for discrete tasks, extract metadata, check duplicates, create via API.

Ticket Metadata:

• Title: Clear, action-oriented
• Description: User story format + acceptance criteria
• Priority: urgent/high/medium/low
• Story points: 1/2/3/5/8/13
• Labels: Auto-detect (security, performance, frontend, backend, sprint-N)

Output format:

✓ Ticket Created: [CWS-015] Fix API authentication bug
Priority: urgent | Points: 3 | Sprint: 1 | Labels: security, backend
URL: https://plane.internal.intelliforia.com/.../CWS-015

See references/create-ticket-from-story.md for full workflow.

2. Audit Board State

Analyze ticket distribution and recommend optimizations.

Audit Checklist:

1. Ticket Clustering - Group related tickets (3+ related → parent issue, 5+ → epic)
2. Label Optimization - Missing labels, redundant labels, new label recommendations
3. Status Distribution - WIP bottlenecks, stale tickets (>14 days in todo)
4. View Recommendations - "My Sprint", "Blocked Items", "Quick Wins", "Tech Debt"
5. Dependency Analysis - Map dependencies, detect circular refs, identify blockers

Audit Depths:

• quick: Basic metrics (<5 seconds)
• standard: With clustering analysis (<15 seconds)
• comprehensive: Full NLP analysis (<60 seconds)

See references/audit-board-state.md for full workflow.

3. Select Next Logical Ticket

Score and recommend optimal ticket based on priority algorithm.

Selection Algorithm:

score = priority_score + effort_score + age_score + dependency_bonus + critical_path_bonus - blocker_penalty

Scoring Weights:

• Priority: urgent=10, high=7, medium=3, low=0
• Effort (favor quick wins): 1-2pts=+5, 3-5pts=+3, 8+pts=-2
• Age (address stale): >14 days=+3, >7 days=+2
• Dependency bonus: +2 per ticket unblocked (cap 10)
• Critical path: +8

Output:

🎯 Recommended: [CWS-004] Fix production build (Score: 21)
Why: URGENT priority, unblocks 2 tickets, on critical path

Alternatives:
1. [CWS-001] API key rotation (18 pts, security critical)
2. [CWS-012] Add CSP (8 pts, quick win - 1 point)

Marking CWS-004 as in-progress...
✓ Status updated, assigned to you, start time logged

See references/select-next-ticket.md for full algorithm.

4. Promote Completed Tickets

After staging merged to main:

1. Query completed tickets in current sprint
2. Verify acceptance criteria met
3. Move to "live" status, add "deployed-production" label
4. Generate changelog from ticket data
5. Send notification email to team

See assets/changelog-email.md for email template.

Hook Integration

Pre-Prompt Hook (Automatic)

Runs before every prompt to check board state.

Checks:

• WIP limit exceeded? (warn if >5 in-progress)
• Current ticket context from git branch
• Dependency conflicts
• Urgent tickets needing attention

Silent mode: Passes without output if no issues.

Stop Hook (Automatic)

Runs at session end to update ticket.

Actions:

1. Detect ticket from git branch (CWS-\d+ pattern)
2. Generate session summary (files changed, commits, duration)
3. Prompt for status update (in-progress/completed/blocked)
4. Append development log to ticket description

BMAD Integration Points

Multi-Workspace Configuration

Config file: ~/.claude/plane-workspaces.json

{
  "workspaces": {
    "intelliforia": {
      "api_key_env": "PLANE_API_KEY",
      "base_url": "plane.internal.intelliforia.com",
      "projects": { "default": "dfb05f73-cab7-4447-a4a1-360bb7ca7177" },
      "wip_limits": { "individual": 3, "team": 7 }
    }
  },
  "detection": {
    "git_remote_patterns": { "intelliforia": "intelliforia" },
    "directory_patterns": { "/home/delorenj/code/intelliforia": "intelliforia" }
  },
  "default_workspace": "intelliforia"
}

Registering a Project

Every project that uses Plane tickets needs two things: a .plane.json in the project root and an entry in the global workspace config.

1. Create .plane.json in the project root

This is the primary detection mechanism (highest priority in the resolution chain). Place it at the repo root alongside CLAUDE.md.

See references/plane-json-template.json for the template.

{
  "workspace": "33god",
  "base_url": "plane.delo.sh",
  "project_id": "ce150fc4-bfd9-4b6f-9f14-6468c18616e3"
}

2. Register in global workspace config

Add the project to ~/.claude/plane-workspaces.json under the workspace's projects map:

{
  "workspaces": {
    "33god": {
      "projects": {
        "ssbnk": "ce150fc4-bfd9-4b6f-9f14-6468c18616e3"
      }
    }
  }
}

The key (e.g., ssbnk) is a human-friendly alias used for lookups when .plane.json is absent.

Finding the project ID

If you don't know the project UUID, query the API:

curl -s -H "X-Api-Key: $PLANE_33GOD_API_KEY" \
  "https://plane.delo.sh/api/v1/workspaces/33god/projects/" \
  | python3 -c "import json,sys; [print(f'{p[\"identifier\"]}: {p[\"id\"]}') for p in json.load(sys.stdin).get('results', json.load(sys.stdin))]"

Or grab it from the Plane UI URL: https://plane.delo.sh/<workspace>/projects/<project_id>/...

Ticket Template

See assets/ticket-template.md for standard ticket format with:

• User story (As a... I want... So that...)
• Acceptance criteria checklist
• Technical notes and dependencies
• Development log (auto-populated by stop hook)

Error Handling

API failures: Retry with exponential backoff (3 attempts), cache locally for later sync

Ticket not found: Search similar IDs, prompt user, offer to create new ticket

Dependency conflicts: Warn user, offer options (work on blocker first, continue anyway, remove dependency)

WIP limit exceeded: Warn but don't block, suggest completing existing work

Quick Reference

# Create ticket
"Create a ticket for fixing the login bug, high priority, 3 points"

# Board audit
"Run a board audit" or "Audit board state --depth comprehensive"

# Next ticket
"What should I work on next?" or "Select next ticket"

# Promote to production
"Promote completed tickets from Sprint 1 and send changelog"

# Check status
"Show sprint progress" or "List my in-progress tickets"