4-maid-development

Development Phase Skill

MANDATORY: QA Gate After EVERY Task

Iron Rule: Task complete → Spawn QA → Wait for result → PASS? Next task : Fix

Task(
  subagent_type="general-purpose",
  prompt="You are a QA Validator. Read .maid/qa/{TASK-ID}.yaml and review modified files. Return JSON with verdict: PASS or FAIL.",
  description="QA validation for {TASK-ID}"
)

• PASS → Proceed to next task
• FAIL → Fix issues in action_required, spawn QA again

Phase Overview

Purpose: Implement solution with quality built-in through TDD.

Entry: Tech spec completed, architecture defined Exit: All features implemented, tests passing, code reviewed

Deliverables

1. Production Code - Clean, documented, follows standards
2. Test Suite - Unit, integration, E2E, >80% coverage
3. Documentation - Code docs, API docs, README updates

TDD Workflow

RED (failing test) → GREEN (make pass) → REFACTOR (clean up) → REPEAT

Frontend Checklist (every UI task)

Before writing any new component:

1. Audit first — search src/components/ for an existing component that can be extended via props. Duplicate only when genuinely impossible to extend.
2. Load skills — invoke ui-ux-pro-max (design quality + accessibility) AND atomic-design (hierarchy placement) before implementing.
3. Name generically — the name must describe WHAT the component IS, not WHERE it is used:

4. Tokens only — every color, spacing, font size, and radius value must reference a CSS variable from src/tokens/. No hardcoded values in component files.
5. Accessibility baseline — every component must pass: color contrast ≥4.5:1, 44×44px touch targets, visible focus ring, ARIA labels on icon-only elements.
6. Visual bar — refer to ui-ux-pro-max style and palette guidance; output must be visually distinctive and consistent with the project's chosen aesthetic direction.

Iron Rules for UI (non-negotiable)

• TODO: define token is a blocker — do not ship a component with a hardcoded hex value
• A component named after a feature (FeatureNameXxx) fails code review
• Missing ui-ux-pro-max skill load for a UI task is a protocol violation

Common Pitfalls

Code Quality

Required:

• Single responsibility functions
• DRY - no copy-paste
• Type hints on public functions
• Meaningful names
• Error handling

Forbidden:

• No any types
• No TODO/FIXME
• No commented-out code
• No test-specific branching

Documentation Standards

File-Level:

/**
 * @file UserService.ts
 * @description Purpose
 * @related ./UserRepository.ts
 */

Function:

/**
 * Creates user account.
 * @param data - User input
 * @returns Created user
 * @throws {ValidationError} If email invalid
 */

QA Gate Enforcement

Per-Task Flow

1. Read Task + QA Criteria (.maid/qa/{task-id}.yaml)
2. Implement Task (TDD)
3. Signal Complete (TodoWrite)
4. SPAWN QA SUB-AGENT (mandatory)
5. Process QA Report → PASS: next task, FAIL: fix & retry

QA Criteria Location

.maid/qa/{task-id}.yaml:

criteria:
  must_achieve:    # What code MUST do
  must_not:        # What code must NEVER do
  not_included:    # Scope boundaries
  best_practices:  # Quality standards

QA Sub-Agent Context (Isolated)

Sees: Epic goal, Story value, Acceptance criteria, Changed files Does NOT see: Tech Spec, Architecture, Developer notes

QA Gate Rules

When QA Fails

1. Read report at .maid/qa/{task-id}-review-{N}.json
2. Fix each issue in action_required
3. Re-spawn QA
4. Repeat until PASS or max cycles

Phase Gate Checklist

• All features per spec
• All tests passing
• Edge cases tested
• Code reviewed
• No test-specific logic in prod
• Documentation updated
• All tasks passed QA gate
• Git: changes staged and ready to commit at phase end

Git Checkpoint (end of phase only)

Work freely throughout Phase 4 — green/red change indicators stay visible while you have uncommitted changes, which helps you track everything you've built.

When ALL tasks are complete and QA passed, make a single phase-level commit:

git add .
git commit -m "feat: phase 4 complete — [brief summary]"

Do NOT push yet. Push happens in Phase 6 after user acceptance. Committing here saves a local checkpoint while keeping everything ready to review.

Role Guidance

Handoff to QA

• Complete, tested code
• Test results + coverage
• Known issues (if any)
• Deployment instructions

⚠️ IRON RULE: Every Message Must End With a Question

This rule is non-negotiable and applies even when the lifecycle orchestrator skill is not loaded.

Every single response you send during this phase MUST end by calling vscode_askQuestions. No exceptions. No informational-only messages. No summaries without a follow-up question.

What this means in practice

Minimum required vscode_askQuestions call at end of every message

If nothing else fits, always end with:

vscode_askQuestions:
  header: "next-step"
  question: "What would you like to do next?"
  options:
    - "▶ Continue"
    - "⏸  Pause here"
    - "🔁 Revise something"

Never do this

❌ Send a message that ends with a period and no question
❌ Send a status update without asking for approval or next action
❌ Complete a task and wait silently for the user to drive

You are the orchestrator. You take the lead. Always move the conversation forward with a question.