Dev Maestro Skill

QUICK REFERENCE

| Item | Value | |------|-------| | URL | http://localhost:PORT | | Install | ~/.dev-maestro | | Default Port | 6010 |

WHEN TO USE

User says "start maestro" / "open kanban" / "show tasks"
User wants to see MASTER_PLAN.md visually
User asks about task status in Kanban view
Task shows wrong status in Dev Maestro (e.g., "PLANNED" instead of "DONE")
User reports "task still shows as planned" after marking it done

WHEN NOT TO USE

User is working on their main project (Dev Maestro is a tool, not a target)
User didn't mention Dev Maestro
You're tempted to "improve" or extend Dev Maestro

WORKFLOW

Step 0: Ask User for Port Preference

Before installing or starting, ask the user:

"What port should Dev Maestro run on? (default: 6010)"

Use their answer for PORT in all subsequent commands. If they say "default" or don't specify, use 6010.

Step 1: Check if Already Running

curl -s http://localhost:PORT/api/status 2>/dev/null && echo "RUNNING" || echo "NOT RUNNING"

Step 2: Install if Needed (Foolproof Method)

Download first, then run (avoids terminal line-wrap issues):

curl -sSL "https://raw.githubusercontent.com/endlessblink/dev-maestro/main/install.sh" -o /tmp/dm-install.sh

bash /tmp/dm-install.sh -m /path/to/docs/MASTER_PLAN.md

Step 3: Start with Custom Port

cd ~/.dev-maestro && PORT=PORT npm start &

Step 4: Verify

sleep 3 && curl -s http://localhost:PORT/api/status

Step 5: Tell User

"Dev Maestro is running at http://localhost:PORT"

API ENDPOINTS

| Method | Endpoint | Purpose | |--------|----------|---------| | GET | /api/status | Check if running | | GET | /api/master-plan | Get tasks from MASTER_PLAN.md | | GET | /api/health/quick | Project health summary | | POST | /api/task/add | Add task (body: {"title":"..."}) |

ANTI-SIDETRACKING RULES

Don't build features for Dev Maestro - It's a separate project
Don't add MCP wrappers - REST API via curl is sufficient
Don't refactor Dev Maestro code - Stay focused on user's actual task
Use curl directly - No abstractions needed

TROUBLESHOOTING

Port in use:

lsof -ti:PORT | xargs kill -9 && cd ~/.dev-maestro && PORT=PORT npm start &

MASTER_PLAN.md not found:

# Check current path
curl -s localhost:PORT/api/status | jq '.masterPlanPath'

# Reconfigure
cd ~/.dev-maestro && ./install.sh --reconfigure

PARSER TROUBLESHOOTING (Task Shows Wrong Status)

Full SOP: docs/sop/SOP-028-dev-maestro-task-sync.md

QUICK FIX (Do This First!)

When a task shows wrong status (e.g., "IN PROGRESS" instead of "DONE"):

# 1. Find ALL occurrences of the task
grep -n "TASK-XXX" docs/MASTER_PLAN.md

# 2. Update EACH location with consistent status (strikethrough + ✅ DONE)

# 3. Restart Dev Maestro (CRITICAL - clears server cache)
lsof -i :6010 -t | xargs kill 2>/dev/null
cd ~/.dev-maestro && nohup npm start > /tmp/dev-maestro.log 2>&1 &

# 4. Hard refresh browser (CRITICAL - clears browser cache)
# Press Ctrl+Shift+R (not just F5)

Why This Happens

MASTER_PLAN.md has tasks in multiple locations:

Summary table (~lines 25-200) - | ~~**TASK-XXX**~~ | ✅ **DONE** ... |
Detailed sections - ### ~~TASK-XXX~~: Title (✅ DONE)

Dev Maestro parses BOTH. If they disagree, you get wrong status.

Marking Tasks Done Correctly

Update ALL occurrences:

| Location | What to Change | |----------|----------------| | Summary table ID | Add ~~ strikethrough: ~~**TASK-XXX**~~ | | Summary table title | Add ✅ **DONE** prefix | | Summary table status column | Change to ✅ **DONE** (date) | | Detailed section header | ### ~~TASK-XXX~~: Title (✅ DONE) | | Detailed section **Status**: line | **Status**: ✅ DONE (date) |

Verify Fix

# All occurrences should show DONE/strikethrough
grep "TASK-XXX" docs/MASTER_PLAN.md

Debug via Browser Console

// Open DevTools (F12) at http://localhost:6010/kanban/
// Look for this in console after page load:
[DEBUG] TASK-XXX: { status: 'done', progress: 100, title: '...' }

Parser Recognizes These Sections Only

## Ideas
## Roadmap
## Current Status
## Active Work
## Known Issues
## Archive
## Technical Debt

Unrecognized sections (e.g., ## PWA Prerequisites) don't reset the parser state, which can cause issues.

Parser Status Detection

The parser looks for these patterns (in order):

| Pattern | Detected Status | |---------|-----------------| | ~~ in ID | done | | DONE, FIXED, ✅ in any cell | done | | REVIEW, 👀 | review | | IN PROGRESS, 🔄 | in-progress | | PAUSED, ⏸️ | paused | | Default | todo |

Known Bug Patterns

Caching: Browser/server cache shows old status → Restart + hard refresh
Inconsistent marking: Table says DONE but detailed section says PLANNED
Missing strikethrough: ID not struck through even if status says DONE