Current Task: $ARGUMENTS

APEX Methodology Skill

Analyze → Plan → Execute → eLicit → eXamine

Complete development workflow for features, fixes, and refactoring.

Step 0: Initialize Tracking (MANDATORY FIRST ACTION)

BEFORE anything else, run this command to initialize APEX tracking:

mkdir -p .claude/apex/docs && cat > .claude/apex/task.json << 'INITEOF' { "current_task": "1", "created_at": "'"$(date -u +"%Y-%m-%dT%H:%M:%SZ")"'", "tasks": { "1": { "status": "in_progress", "started_at": "'"$(date -u +"%Y-%m-%dT%H:%M:%SZ")"'", "doc_consulted": {} } } } INITEOF echo "✅ APEX tracking initialized in $(pwd)/.claude/apex/"

This creates:

• .claude/apex/task.json

• Tracks documentation consultation status

• .claude/apex/docs/

• Stores consulted documentation summaries

The PreToolUse hooks will BLOCK Write/Edit until documentation is consulted.

Workflow Overview

┌─────────────────────────────────────────────────────────────────┐ │ APEX WORKFLOW │ ├─────────────────────────────────────────────────────────────────┤ │ 00-init-branch → Create feature branch │ │ 00.5-brainstorm → Design-first questioning (B) ← NEW │ │ 01-analyze-code → Understand codebase (A) │ │ 02-features-plan → Plan implementation (P) │ │ 03-execution → Write code with TDD (E) ← UPDATED │ │ 03.5-elicit → Expert self-review (L) │ │ 03.7-verification → Functional resolution check (V) ← NEW │ │ 04-validation → Verify quality (X) │ │ 05-review → Self-review │ │ 06-fix-issue → Handle issues │ │ 07-add-test → Write tests (TDD cycle) │ │ 08-check-test → Run tests │ │ 09-create-pr → Create Pull Request │ └─────────────────────────────────────────────────────────────────┘

Skills Integration

Phase Skill Invocation

00.5 brainstorming

Questions → alternatives → design doc → approval

03 tdd

RED (test) → GREEN (code) → REFACTOR cycle

03.7 verification

Re-read request → check criteria → confirm resolution

Phase References

Phase File Purpose

00 references/00-init-branch.md

Create feature branch

01 references/01-analyze-code.md

Explore + Research (APEX A)

02 references/02-features-plan.md

TaskCreate planning (APEX P)

03 references/03-execution.md

Implementation (APEX E)

03.5 references/03.5-elicit.md

Expert self-review (APEX L) ← NEW

04 references/04-validation.md

sniper validation (APEX X)

05 references/05-review.md

Self-review checklist

06 references/06-fix-issue.md

Fix validation/review issues

07 references/07-add-test.md

Write unit/integration tests

08 references/08-check-test.md

Run and verify tests

09 references/09-create-pr.md

Create and merge PR

Quick Start

Standard Feature Flow

1. 00-init-branch → git checkout -b feature/xxx
2. 00.5-brainstorm → Ask questions, propose alternatives, get design approval
3. 01-analyze-code → explore-codebase + research-expert
4. 02-features-plan → TaskCreate task breakdown
5. 03-execution → TDD: write test FIRST, then implement (files <100 lines)
6. 03.5-elicit → Expert self-review (elicitation techniques)
7. 03.7-verification → Verify functional resolution against original request
8. 04-validation → sniper agent (code quality)
9. 05-review → Self-review
10. 09-create-pr → gh pr create

Bug Fix Flow

1. 00-init-branch → git checkout -b fix/xxx
2. 01-analyze-code → Understand bug context
3. 07-add-test → TDD: write failing test FIRST (RED)
4. 03-execution → Fix the bug (GREEN)
5. 08-check-test → Verify test passes + no regressions
6. 03.7-verification → Verify original bug is functionally resolved
7. 04-validation → sniper agent
8. 09-create-pr → gh pr create

Hotfix Flow

1. 00-init-branch → git checkout -b hotfix/xxx
2. 03-execution → Minimal fix only
3. 03.7-verification → Verify fix resolves the issue
4. 04-validation → sniper agent
5. 08-check-test → Run tests
6. 09-create-pr → Urgent merge

Core Rules

File Size (ABSOLUTE)

🚨 STOP at 90 lines → Split immediately ❌ NEVER exceed 100 lines 📊 Target: 50-80 lines per file

Interface Location

✅ src/interfaces/ (global) ✅ src/types/ (type definitions) ✅ Contracts/ (PHP/Laravel) ❌ NEVER in component files

Agent Usage

01-analyze: explore-codebase + research-expert (PARALLEL) 04-validate: sniper (MANDATORY after ANY change)

APEX Phases Explained

A - Analyze

ALWAYS run 2 agents in parallel:

1. explore-codebase → Map project structure → Find existing patterns → Identify change locations

2. research-expert → Verify official documentation → Confirm API methods → Check best practices

P - Plan

ALWAYS use TaskCreate:

1. Break down into tasks
2. Each task <100 lines
3. Plan file splits FIRST
4. Map dependencies (addBlockedBy)

E - Execute (with TDD)

FOLLOW plan strictly with TDD cycle:

1. Create interfaces FIRST
2. Write failing test (RED) → verify it fails
3. Write minimal code (GREEN) → verify it passes
4. Refactor → keep tests green
5. Monitor file sizes (<100 lines)
6. Write JSDoc/comments
7. Atomic commits per task

See tdd skill for detailed RED-GREEN-REFACTOR rules.

V - Verify (Functional Resolution)

BEFORE sniper, verify functional correctness:

1. Re-read original request
2. List all acceptance criteria
3. Verify each with evidence
4. Check for regressions
5. Confirm: "Problem is RESOLVED"

See verification skill for detailed checklist.

X - eXamine

ALWAYS run sniper:

6-phase validation:

1. explore-codebase
2. research-expert
3. grep usages
4. run linters
5. apply fixes
6. ZERO errors

Branching Strategy

Branch Naming

feature/ISSUE-123-short-description fix/ISSUE-456-bug-name hotfix/ISSUE-789-urgent-fix refactor/ISSUE-321-cleanup docs/ISSUE-654-readme test/ISSUE-987-coverage

Best Practices (2025)

✅ Short-lived branches (1-3 days) ✅ Small, focused changes ✅ Sync frequently with main ✅ Squash and merge

Commit Convention

Format

<type>(<scope>): <description>

Types: feat, fix, refactor, docs, test, chore Scope: component/feature name Description: imperative mood, <50 chars

Examples

feat(auth): add JWT authentication fix(cart): resolve quantity validation refactor(api): extract fetch utilities test(auth): add login component tests

Validation Requirements

Before PR

□ sniper passes (ZERO errors) □ All tests pass □ Build succeeds □ Self-review complete □ No console.logs □ No TODO unaddressed

Code Quality

□ Files <100 lines □ Interfaces in correct location □ JSDoc on all exports □ No any types □ Error handling complete

PR Guidelines

Title Format

feat(auth): add social login with Google fix(cart): resolve quantity update bug refactor(api): extract fetch utilities

Description Must Include

□ Summary (1-3 bullets) □ Changes (added/modified/removed) □ Related issues (Closes #xxx) □ Test plan (checkboxes) □ Screenshots (if UI changes)

Flow Diagram

                START
                  │
                  ▼
          ┌───────────────┐
          │ 00-init-branch│
          └───────┬───────┘
                  │
                  ▼
          ┌───────────────┐
          │ 00.5-brain-   │ ← brainstorming skill (NEW)
          │ storm         │   questions → design → approval
          └───────┬───────┘
                  │
                  ▼
          ┌───────────────┐
          │ 01-analyze    │ ← explore + research
          └───────┬───────┘
                  │
                  ▼
          ┌───────────────┐
          │ 02-plan       │ ← TaskCreate
          └───────┬───────┘
                  │
                  ▼
          ┌───────────────┐
          │ 03-execute    │ ← TDD: test first (RED→GREEN)
          └───────┬───────┘
                  │
                  ▼
          ┌───────────────┐
          │ 03.5-elicit   │ ← expert self-review
          └───────┬───────┘
                  │
                  ▼
          ┌───────────────┐
          │ 03.7-verify   │ ← verification skill (NEW)
          └───────┬───────┘   functional resolution check
                  │
                  ▼
          ┌───────────────┐
          │ 04-validate   │ ← sniper (code quality)
          └───────┬───────┘
                  │
                  ▼
          ┌───────────────┐
          │ 05-review     │
          └───────┬───────┘
                  │
                  ▼
          ┌───────────────┐
          │ 09-create-pr  │
          └───────┬───────┘
                  │
                  ▼
                DONE

NEVER

❌ Skip explore-codebase or research-expert ❌ Assume API syntax without verification ❌ Create files >100 lines ❌ Put interfaces in component files ❌ Skip sniper after changes ❌ Merge without tests ❌ Large PRs (>400 lines)

Reference Files

All detailed guides in references/ directory:

references/ ├── 00-init-branch.md # Branch creation ├── 01-analyze-code.md # Code analysis ├── 02-features-plan.md # Planning ├── 03-execution.md # Implementation ├── 04-validation.md # Validation ├── 05-review.md # Self-review ├── 06-fix-issue.md # Issue fixes ├── 07-add-test.md # Test writing ├── 08-check-test.md # Test running └── 09-create-pr.md # PR creation

Language-Specific References

Framework-specific APEX methodology guides:

Framework Directory Tools

Laravel references/laravel/

Pest, Larastan, Pint

Next.js references/nextjs/

Vitest, Playwright, ESLint

React references/react/

Vitest, Testing Library, Biome

Swift references/swift/

XCTest, SwiftLint, swift-format

Auto-Detection

Project Type → References Used ───────────────────────────────────── composer.json → references/laravel/ next.config.* → references/nextjs/ vite.config.* → references/react/ Package.swift → references/swift/ Default → references/ (generic)

Structure (Each Framework)

references/[framework]/ ├── 00-init-branch.md # Framework-specific branching ├── 01-analyze-code.md # Framework exploration tools ├── 02-features-plan.md # Planning patterns ├── 03-execution.md # SOLID implementation ├── 04-validation.md # Linters and formatters ├── 05-review.md # Framework checklist ├── 06-fix-issue.md # Common fixes ├── 07-add-test.md # Testing patterns ├── 08-check-test.md # Test commands └── 09-create-pr.md # PR template