dev

name	dev
description	Develop phase with exploration and plan validation
model	opus
argument-hint	spec=<path> phase=<number> [done=<phases>] [auto=<bool>]
hooks	{"PostToolUse":[{"matcher":"Edit|Write","hooks":[{"type":"command","command":"if [[ -d \"backend\" ]]; then\n cd backend && go build ./... 2>&1 | head -10 && golangci-lint run ./... 2>&1 | head -20 || true\nfi\n","once":true}]}]}

YOU ARE EXECUTING THE /dev SKILL. The user triggered this skill. Follow ALL instructions below step by step. Do NOT treat this as a freeform conversation - execute the skill workflow.

Follow CLAUDE.md rules.

Ultra Think Strategy

Ultra think before each phase transition:

• After exploration results: reflect on completeness before planning
• Before implementation: consider edge cases, patterns to follow, potential issues
• After validation: ensure the approach aligns with user intent

---

1. UNDERSTAND

• Read spec: $ARGUMENTS.spec
• Identify phase: $ARGUMENTS.phase
• Phases completed: $ARGUMENTS.done
• Extract from phase description:
  • Scope: backend / frontend / both
  • Files to create/modify
  • Libraries needed

---

2. EXPLORE (PARALLEL)

Launch focused agents in a single message (parallel execution). There is no upper limit on agent count. Spawn one agent per distinct concern, area, or file-cluster the task actually has, and scale up freely with its breadth. The lists below are a starting menu, not a quota: add as many agents as full coverage requires.

Agent-count principle

• You decide the count from the actual scope. Assess how many distinct concerns / areas / file-clusters the task really spans on this codebase, and launch one focused agent for each. Do not anchor to a fixed number or to file counts.
• No ceiling, real floor. Use at least 2 agents per domain in scope (1 only for a genuinely trivial single-file change). Above that floor there is no maximum; on a large codebase the realistic count usually sits well above it.
• One distinct focus per agent. Split by concern so two agents never run the same search. Add agents to widen coverage, never to duplicate it.
• No batching. Launch them all in one message; the harness schedules them, so you never hold back to stay under a number.

Backend Agents (≥2 when backend in scope, one per distinct concern, no maximum)

1. Domain & data flow - explore-codebase: "Find entities, repository interfaces, value objects, and DTOs related to [feature] in backend/internal/domain/ and backend/internal/application/dto/"
2. Usecases & business logic - explore-codebase: "Find usecases related to [feature] in backend/internal/application/usecases/. Read their Execute methods, dependencies, and error handling"
3. Handlers & routing - explore-codebase: "Find HTTP handlers and routes related to [feature] in backend/internal/presentation/. Check middleware, validation, response patterns"
4. Infrastructure & services - explore-codebase: "Find repo implementations, external service adapters, and config related to [feature] in backend/internal/infrastructure/"
5. Similar patterns - explore-codebase: "Find the most similar existing feature to [feature] in backend/. I need to replicate its patterns"

Frontend Agents (≥2 when frontend in scope, one per distinct concern, no maximum)

1. Components & UI - explore-codebase: "Find components related to [feature] in frontend/src/components/. Check props, state, Shadcn UI usage"
2. Hooks & state - explore-codebase: "Find hooks, React Query calls, and state management related to [feature] in frontend/src/hooks/ and frontend/src/lib/"
3. Pages & routing - explore-codebase: "Find pages and layouts related to [feature] in frontend/src/app/. Check route structure, data fetching, i18n"
4. Types & API layer - explore-codebase: "Find TypeScript types, API client functions related to [feature] in frontend/src/types/ and frontend/src/lib/"
5. Similar patterns - explore-codebase: "Find the most similar existing feature to [feature] in frontend/src/. I need to replicate its patterns"

The supporting agents below fan out the SAME way as the code agents: one agent per distinct concern, no maximum. None of them is capped at a single instance.

Database Agents (≥1 when DB in scope, one per distinct concern, no maximum)

Launch one explore-db per distinct DB concern in the same single message. One agent is enough for a single-table lookup; scale up freely when the phase spans multiple table clusters, both dev and prod, or several concerns. First token of each prompt selects the env (dev/prod, defaults to dev).

1. Schema & relationships - explore-db: "dev - Map tables and foreign keys related to [feature]: columns, types, FK relationships"
2. Constraints & policies - explore-db: "dev - Inspect constraints and RLS policies (if used) on tables related to [feature]"
3. Migrations & advisors - explore-db: "dev - List migrations touching [feature] tables, run get_advisors for security/perf issues"

Add one agent per distinct table cluster, or to cover prod alongside dev.

Documentation Agents (≥1 when external docs needed, one per library/feature, no maximum)

Launch one explore-docs per distinct library or per distinct feature within a library. One agent is enough for a single lib question; scale up when the phase touches multiple libraries or several independent features of one.

1. [library A] - explore-docs: "[library A] [specific feature] documentation"
2. [library B] - explore-docs: "[library B] [specific feature] documentation"

Web-research Agents (≥1 when external research needed, one per topic, no maximum)

Launch one websearch per distinct external question. One agent is enough for a single topic; scale up when there are several independent questions.

1. [topic A] - websearch: "[topic A] best practices 2025 2026"
2. [topic B] - websearch: "[topic B] ..."

---

2.5 POST-EXPLORATION CHECK

After agents return, verify coverage across all dimensions:

1. Full code path traced? Can I trace handler -> usecase -> repository -> DB (backend) and page -> hook -> API -> component (frontend)? If gaps -> launch targeted explore-codebase
2. Similar patterns identified? Do I have a reference implementation to follow? If not -> launch explore-codebase
3. Data model complete? Tables, columns, relationships, policies known? If not -> launch additional parallel explore-db agents (one per missing concern / cluster / env)
4. Library docs sufficient? If not -> launch additional parallel explore-docs agents (one per missing library / feature)

Do NOT proceed with incomplete context.

---

3. SHOW PLAN

Display enriched plan:

## Phase $ARGUMENTS.phase

### Files to Create
- `path/file` - [purpose]

### Files to Modify
- `path/file:XX` - [what to change]

### Patterns to Reuse (from exploration)
- [existing code patterns found]

### Order
Backend: Domain -> Application -> Infrastructure -> Presentation
Frontend: Types -> API -> Hooks -> Components -> Pages

---

4. VALIDATE

If $ARGUMENTS.auto is true:

• Skip the gate. Log "Auto-confirmed (auto=true), proceeding to implementation." and go directly to step 5.

Otherwise (default):

• Ask with AskUserQuestion: "Proceed with implementation?"
  • "Implement"
  • "Modify"

---

5. IMPLEMENT

After validation, implement in appropriate order:

Backend: Domain -> Application -> Infrastructure -> Presentation

• context.Context as first parameter for I/O
• Follow Clean Architecture patterns
• Complete error handling
• Write unit tests for all new usecases/services (colocated *_test.go)
• Follow existing test patterns (testify, hand-written mocks, *Env struct helper)
• Tests must cover happy path + main error cases

Frontend: Types -> API -> Hooks -> Components -> Pages

• useTranslations from next-intl for ALL user-facing text
• Shadcn UI for standard components
• Strict TypeScript (no any)
• Write unit tests for new components with branching logic, new hooks, and new utility/parser functions (colocated *.test.ts / *.test.tsx)
• Follow existing test patterns (vitest + @testing-library/react, vi.mock for module-level deps, jest-dom matchers via the shared test setup)
• Tests must cover happy path + main error / edge cases

For significant UI: Skill(skill="frontend-design:frontend-design")

---

6. VERIFY

# Backend
cd backend && go build ./... && go vet ./... && golangci-lint run ./... && go test ./...
# Frontend
cd frontend && npm run test:run && npm run build

Backend and frontend tests are MANDATORY: All existing tests must pass (zero regressions). If a test fails, fix it before proceeding.

Database verification (if schema/policies changed): run get_advisors via explore-db (dev/prod).

---

7. UPDATE SPEC

Check off completed items in the Execution Plan of the spec file.

---

Rules

• EXPLORE FIRST - Always explore before implementing
• REUSE - Existing code/patterns as much as possible
• VALIDATE - Always ask before implementing
• STAY IN SCOPE - Only the specified phase