Task — Systematic Implementation Workflow

Standard 5-phase workflow for all implementation tasks with built-in quality gates.

<essential_principles>

Serena Think Checkpoints (Mandatory)

Call the following Serena tools at the specified points. Never skip them.

Checkpoint	Tool	When	Purpose
Adherence Gate	mcp__serena__think_about_task_adherence	Before each code edit in Phase 3	Confirm still aligned with original task
Completion Gate	mcp__serena__think_about_whether_you_are_done	Before exiting Phase 4 (Verify)	Confirm all work is truly complete

After Phase 1 and again after Phase 2, do a short information sufficiency self-check in prose (requirements understood, relevant code located, plan covers acceptance criteria and verification). If gaps remain, gather more context before continuing—do not rely on a removed Serena tool.

Introspection Markers (Always Active)

Use these markers throughout all phases to make reasoning visible:

• 🤔 Reasoning — "🤔 The error suggests a missing dependency"
• 🎯 Decision — "🎯 Choosing approach A over B because..."
• ⚡ Performance — "⚡ This query may cause N+1"
• 📊 Quality — "📊 Checking consistency with existing patterns"
• 💡 Insight — "💡 This pattern can be reused for..."

Safety Rules

• Before destructive operations (delete, overwrite, reset): Always confirm with user
• Before code edits: Call think_about_task_adherence
• Never auto-commit: Phase 5 waits for user instruction to commit/push
• Quality gate required: Phase 4 must pass before Phase 5

</essential_principles>

Phase 1: Investigate

Understand the task and gather context.

1. Parse task requirements from user input
2. Read relevant code files (Grep, Read, Serena symbolic tools)
3. Check external libraries with Context7 if needed
4. Identify existing patterns and conventions
5. Information sufficiency self-check — Confirm you understand the task, have seen the relevant code paths, and know project conventions well enough to plan. If not, keep reading or ask the user before Phase 2.

Tools: Grep, Read, Glob, mcp__serena__find_symbol, mcp__serena__get_symbols_overview, mcp__context7__query-docs

Phase 2: Plan

Break down the task and design the approach.

1. Create task breakdown with TodoWrite
2. Identify parallelizable steps: Plan: 1) Parallel [Read A, B] → 2) Edit → 3) Parallel [Test, Lint]
3. Save plan to Serena Memory: mcp__serena__write_memory("plan_<topic>", content)
4. Plan completeness self-check — Confirm the plan and todos cover acceptance criteria, edge cases, and how you will verify the change. Revise the plan if anything important is missing.

Output: TodoWrite entries with clear acceptance criteria per step.

Phase 3: Implement

Execute the plan with continuous adherence checks.

For each implementation step:

1. Mark TodoWrite item as in-progress
2. 🔶 think_about_task_adherence — Still on track?
3. Edit code (Edit, Write)
4. Use introspection markers (🤔🎯⚡📊💡) to explain reasoning
5. Mark TodoWrite item as complete

Rules:

• No // TODO: implement later — write working code
• No mock objects outside tests
• Follow existing code patterns and conventions
• Confirm with user before destructive operations

Phase 4: Verify

Run quality checks and validate correctness.

Standard Verification (always)

Run in parallel where possible:

# Parallel execution
pnpm lint &
pnpm typecheck &
pnpm test &
pnpm build &
wait

If any check fails → investigate root cause → fix in Phase 3 → re-verify.

--frontend-verify (when flag is provided)

Visual verification across platforms. Auto-detect platform from package.json:

Dependency	Platform	Preflight	Verification Tool
(default)	Web	kill-port <port> && pnpm dev	playwright-cli (open --headed, snapshot, screenshot)
electron	Electron	pnpm electron:dev	/qa-electron skill (playwright-cli attached to Electron CDP)
expo / react-native	Mobile	mcp__ios-simulator__open_simulator	iOS Simulator MCP (screenshot, ui_tap, ui_swipe)
commander / inquirer / oclif	CLI	shell session	Shellwright MCP (TUI/CLI operation and output verification)

Frontend Verify Workflow:

0. Pre-flight knowledge: invoke /dnd to load the drag-and-drop coordinate protocol. Ref-based drag reports false success on dnd-kit and similar libraries — required before any Web or Electron interaction.
1. Preflight: kill-port <port> && pnpm dev, confirm playwright-cli is available (Web direct; Electron via playwright-cli attach --cdp=http://localhost:9222)
2. Scenario creation: Design test scenarios based on changes, save to Serena Memory
3. Execute: Run each scenario via playwright-cli, take screenshot after each step
4. Judge: All pass → continue. Any fail → return to Phase 3

Authentication for Frontend Verify

When verifying authenticated apps (SaaS dashboards, admin panels, OAuth-protected pages), use playwright-cli's auth persistence:

Strategy	Command	Use Case
state-save / state-load	playwright-cli state-save auth.json	Session cookies + localStorage. Best for most web apps
--profile <dir>	playwright-cli open <url> --profile ./browser-data	Full Chromium user data dir. Best for complex OAuth (Google, GitHub SSO)

OAuth Flow:

1. playwright-cli open <login-url> --headed (must be headed for OAuth redirects)
2. Complete OAuth manually or via snapshot + fill + click
3. playwright-cli state-save auth.json to persist session
4. Future runs: playwright-cli state-load auth.json before navigating to app

Security:

• Add auth.json, browser-data/ to .gitignore
• State files contain session secrets — treat as credentials
• Use --headed for initial OAuth setup (redirects require visible browser)

Completion Gate

🔶 think_about_whether_you_are_done — Is everything truly complete?

Phase 5: Complete

Report results and wait for user instruction.

1. Present verification summary to user:
   • What was changed (files, functions)
   • Test results
   • Screenshots (if --frontend-verify)
2. Update TodoWrite — mark all items complete
3. ⏸️ Wait for user instruction to commit/push
4. On user confirmation: git commit && git push

Quick Reference

/task fix the login button styling
/task add dark mode support --frontend-verify
/task refactor the API error handling

Phase Flow Diagram

[Investigate] → 🔶 info gate
     ↓
  [Plan] → 🔶 info gate
     ↓
[Implement] → 🔶 adherence gate (per edit)
     ↓
 [Verify] → 🔶 completion gate
     ↓
[Complete] → ⏸️ wait for user → commit/push