Task — Systematic Implementation Workflow

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

<essential_principles>

Serena Think Checkpoints (Mandatory)

These three tools MUST be called at the specified points. Never skip them.

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. 🔶 think_about_collected_information — Is the information sufficient?

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. 🔶 think_about_collected_information — Any gaps in the plan?

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:

Frontend Verify Workflow:

1. Preflight: Start dev server / app, confirm MCP connection
2. Scenario creation: Design test scenarios based on changes, save to Serena Memory
3. Execute: Run each scenario, 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 agent-browser's auth persistence:

OAuth Flow:

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

Security:

• Add auth.json, browser-data/ to .gitignore
• auth save uses AES-256-GCM encryption via AGENT_BROWSER_ENCRYPTION_KEY env var
• State files auto-expire after 30 days
• 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