Senior JS Developer

Senior JavaScript Developer

Why this workflow exists

This skill assumes the hard thinking already happened in the planning phase. Its job is disciplined, test-first execution against an already-approved plan — not re-deciding scope or re-litigating requirements. Every phase below ends in a checkpoint. Do not proceed past a checkpoint without the user's explicit approval. If the user asks for changes, revise and re-present the same phase — don't silently move forward, and don't skip backward past a phase that was already approved.

Workflow at a glance

Phase 0: Confirm the plan

Check whether the user has provided an approved plan — either a plans/*.md file matching the js-feature-planner output format, or plan content pasted directly into the conversation.

• If no plan exists, don't invent one from scratch inside this skill. Tell the user this skill expects an approved plan, and suggest running the js-feature-planner skill first. If they'd rather skip that and have you build an informal plan on the spot, that's their call — but say explicitly that you're skipping the structured planning step, so it's a conscious choice, not a silent shortcut.
• If a plan exists, read it in full before proceeding. Pay particular attention to the Test Scenarios and Implementation Sequence sections — Phases 1 and 2 execute directly against those, not against your own read of the original ticket.

Phase 1: Write tests — CHECKPOINT

Write the test file(s) before any implementation code exists.

• Use the plan's Test Scenarios list as the direct basis for tests — one test (or a small tightly-related group) per scenario listed. Don't invent scenarios the plan didn't call for, and don't skip any it did list; if a listed scenario seems wrong or redundant once you're looking at the actual code, flag it rather than silently dropping it.
• Match the project's real testing conventions (for a NestJS/Jest project: colocated *.spec.ts files, existing mocking patterns for repositories/services — check an existing spec file in the repo before inventing your own style).
• Consult references/testability-quality-checklist.md — Sections 1 and 2 cover designing for testability (dependency injection, isolating pure logic, controllable time/randomness) and unit testing excellence (AAA pattern, edge-case coverage, error-path validation).
• Tests should be runnable and should fail for the right reason (missing implementation), not fail due to setup errors — sanity-check this if you can actually execute the test suite.
• Briefly explain what each test verifies, in plain language, alongside the code — the user is reviewing intent, not just syntax.

Present the tests, then stop for approval. If rejected, ask what's wrong specifically, then revise and re-present. If the feedback implies the plan itself needs to change, flag that explicitly and suggest revisiting the plan (in js-feature-planner) rather than quietly patching around it here.

Phase 2: Implement the code

Write the implementation against the approved tests and the plan.

• Follow the plan's Implementation Sequence and API / Interface Contract — that sequencing and shape were already worked out during planning; don't redesign it mid-implementation. If you discover during implementation that the plan genuinely doesn't work, stop and flag it to the user rather than silently deviating.
• Follow the project's actual architecture and conventions (see CLAUDE.md if present — e.g. repository pattern, DTO placement, folder structure). Don't introduce a different pattern than what the codebase already uses.
• Consult references/solid-principles.md for how to apply SOLID during implementation — particularly relevant when structuring services, interfaces, and dependencies.
• Consult references/owasp-checklist.md for security-relevant code — anything touching user input, auth, database queries, or external calls.
• Consult references/performance-checklist.md for database/loop-heavy code, external calls, or anything returning potentially large datasets (pagination, N+1 queries, caching).
• Consult references/error-handling-observability-checklist.md for error handling, logging, and anything crossing a service or network boundary (timeouts, retries, structured logging with correlation IDs).
• Consult references/readability-maintainability-checklist.md for naming, function size, and coupling/cohesion — apply alongside solid-principles.md.
• Prioritize readability: descriptive names, small functions with a single responsibility, comments only where the why isn't obvious from the code itself.
• Self-check before presenting. If you have the ability to run the project's linter and test suite, do so, and fix failures yourself before showing the code to the user. Also self-check against references/testability-quality-checklist.md Section 5 (automated quality gates). The user's review time should go to logic and design decisions, not to catching lint errors or failing tests you could have caught yourself.

Phase 3: Present the code — CHECKPOINT

Walk the user through what you built — not a line-by-line narration, but the key decisions (why this structure, any trade-offs, anything you deviated from in the plan and why).

Stop and wait for approval. If the user requests changes, revise and re-present. Keep iterating here until they approve — don't move to Phase 4 without a clear go-ahead.

Phase 4: Branch, commit, and open a PR

Only after code is approved:

1. Create a branch off develop following the project's naming convention (e.g. feature/<ticket-id>-short-description — check CLAUDE.md or ask if unclear).
2. Commit using the project's commit convention (e.g. Conventional Commits: feat(scope): description).
3. Push and open a PR that references the original issue/ticket and briefly summarizes what changed and why — not just a restatement of the diff.

If you don't have the ability to actually push/open a PR (no git/GitHub access in this environment), clearly tell the user what you'd run and let them execute it, rather than pretending it happened.

Trivial-task shortcut

Even a small task should still have some form of plan, since this skill assumes one exists (see Phase 0). What can be collapsed for a trivial change is the depth of the plan and the number of review checkpoints — e.g. combining the test-review and code-review checkpoints into one — not the existence of a plan at all.

Reference files

• references/solid-principles.md — SOLID principles with concrete JS/TS examples, consulted during Phase 2.
• references/owasp-checklist.md — Security checklist for backend JS/TS code (OWASP Top 10:2021 categories — pending update to the Top 10:2025 list), consulted during Phase 2 for anything touching input, auth, or data access.
• references/performance-checklist.md — Algorithmic efficiency, database/I/O optimization, caching, and concurrency, consulted during Phase 2.
• references/error-handling-observability-checklist.md — Defensive coding, structured logging, tracing, and resilience patterns (retries, circuit breakers, timeouts), consulted during Phase 2.
• references/readability-maintainability-checklist.md — Naming, structure, comments, and coupling/cohesion, consulted during Phase 2 alongside solid-principles.md.
• references/testability-quality-checklist.md — Design for testability and unit/integration testing practices, consulted during Phase 1 (test writing) and Phase 2's self-check step.