build-api

Backend API Development Workflow

Build backend API endpoints, services, and database changes following NestJS patterns, Prisma schema design, and the project's clean architecture conventions.

[!CAUTION] Scope boundary: This skill implements backend code and commits it. It does NOT create pull requests, push to remote, run code reviews, or submit anything for merge. When implementation and commits are complete, stop and suggest the user run /review-code next.

Step 1: Define API Requirements

Ensure we are on a feature branch based on the latest main. Always fetch first:

git fetch origin main

If on main, create a new feature branch from the latest origin/main:

git checkout -b feature/<feature-slug> origin/main

If already on an existing feature branch, rebase it onto the latest origin/main to pick up any changes:

git status --porcelain

If the working tree is dirty, stash changes before rebasing:

git stash push -m "build-api: stash before rebase"
git rebase origin/main
git stash pop

If the working tree is clean, rebase directly:

git rebase origin/main

If the user provides a GitHub issue number (e.g., /build-api 42 or /build-api #42), fetch the issue and signal work is in progress (see AGENTS.md "Label Management" for rules):

gh issue view <number> --json title,body,labels,state,number

# Single-developer constraint: only one issue should be in-progress at a time.
# First, remove in-progress from any other issue that has it:
gh issue list --label "in-progress" --state open --json number --jq '.[].number' | while read n; do
  gh issue edit "$n" --remove-label "in-progress"
done

gh issue edit <number> --add-label "in-progress"

Verify the issue is tracked on the Product Roadmap project board. If not, add it:

# --limit 200 covers the current board size; increase if the project grows beyond 200 items
EXISTING=$(gh project item-list {PROJECT_NUMBER} --owner {OWNER} --format json --limit 200 \
  | python3 -c "
import json, sys
data = json.load(sys.stdin)
for item in data.get('items', []):
    # <number> must be an integer literal, e.g., == 42, not == '42'
    if item.get('content', {}).get('number') == <number>:
        print(item['id'])
        break
")

if [ -z "$EXISTING" ]; then
  ITEM_ID=$(gh project item-add {PROJECT_NUMBER} --owner {OWNER} --url "https://github.com/{OWNER}/{REPO}/issues/<number>" --format json | python3 -c "import json,sys; print(json.load(sys.stdin)['id'])")
  echo "Warning: Issue #<number> was not on the project board. Added it now (item $ITEM_ID)."
fi