Web Backend Spec

/magi:web-backend-spec — backend elaboration

You are the coordinator. Add a backend-specific section to a sprint's SPEC.md. You do not write production code. Read references/domain/web/backend.md before starting.

0. Preflight

PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-}"
[[ -z "$PLUGIN_ROOT" ]] && PLUGIN_ROOT="$(cd "$(dirname "$BASH_SOURCE[0]")/../.." 2>/dev/null && pwd)"
USER_CONFIG="$HOME/.config/magi-workflow/config.json"

If config missing → tell user to run /magi:setup.

0.5. State preflight (auto-refuse if not allowed)

STATE_JSON=$(bash "$PLUGIN_ROOT/scripts/shared/detect-state.sh")
blocked=$(jq -r '.disallowed_skills["web-backend-spec"] // empty' <<<"$STATE_JSON")
if [[ -n "$blocked" ]]; then
  reason=$(jq -r '.disallowed_skills["web-backend-spec"].reason' <<<"$STATE_JSON")
  suggest=$(jq -r '.disallowed_skills["web-backend-spec"].suggest' <<<"$STATE_JSON")
  echo "Cannot run /magi:web-backend-spec: $reason"
  echo "Suggested: $suggest"
  exit 1
fi

--force skips preflight (advanced/recovery only).

1. Locate sprint + spec

Find the sprint folder (default: most recent; or --sprint <num>-<slug>). The folder must contain a plan-equivalent file. Identify which exists (priority order):

• If SPEC.md exists → use SPEC.md as the target.
• If only PLAN.md exists → use PLAN.md as the target. Do NOT rename or "upgrade" PLAN.md to SPEC.md — that is a separate decision the user makes via /magi:plan, not forced by web-* skills.
• If only TICKET.md exists → use TICKET.md as the target.
• If none exists → abort and tell the user to run /magi:plan first.

2. Detect stack

Per references/domain/web/backend.md "Stack discovery". Capture:

• Web framework (Express / Fastify / Next route handlers / FastAPI / Django / Rails / Go net/http / etc.)
• Language (TS / Python / Go / Rust / Ruby)
• ORM (Prisma / TypeORM / SQLAlchemy / GORM / Active Record)
• DB (Postgres / MySQL / SQLite / Mongo / Redis)
• Auth scheme (JWT / session / OAuth proxy)
• API style (REST / GraphQL / gRPC / tRPC)
• Background jobs (BullMQ / Sidekiq / Celery / Cloud Tasks / k8s CronJob)

Ask the user once if anything is ambiguous.

3. Identify backend-relevant scope

Read PLAN/SPEC. Pick out the items that need backend work:

• New endpoints or fields
• Schema changes (new table, new column, index, constraint)
• New external integration (third-party API, webhook)
• New authn/authz rule
• New background job
• New SLA / performance constraint

Out-of-scope items (pure UI, infra-only) are skipped here.

4. Generate the Backend section

Following references/domain/web/backend.md "Deliverable" structure:

a. API contract — write SCHEMA FIRST

For REST: produce an OpenAPI excerpt (inline, or as magi/<num>-<slug>/openapi.yaml). For GraphQL: SDL excerpt.

Cover the fields in the reference's "Contract review checklist":

• Versioning, pagination, filtering, errors, idempotency, rate limits, CORS, auth scopes.

b. Data model changes

If the schema changes:

• Migration plan (file names, order, dependencies)
• Online migration strategy if the table is populated
• Indexes & constraints
• Rollback strategy
• Backup taken first? (yes for irreversible changes)

c. Authn/authz matrix

Per endpoint:

d. Validation & safety

• Validation library (zod / yup / pydantic / validator).
• Sanitisation rules for user-generated content.
• Path traversal / SQL injection / XSS / CSRF surfaces.
• What gets logged vs masked.

e. Idempotency & retries

For mutating endpoints: idempotency-key support; replay window; storage.

f. Observability

Per endpoint or per feature:

• Structured log fields
• Metrics (counter, latency p50/p95/p99, error rate)
• Trace span shape
• Alert thresholds

g. Test plan

Three layers from the reference:

• Unit (business logic, validators)
• Integration (DB roundtrip, transaction)
• Contract (OpenAPI / SDL conformance test) — use template from reference

Include the exact test command(s).

h. Open questions

What's unresolved?

5. Append to the target document

Append under ## Backend top-level heading in whichever plan-equivalent file was identified in §1 (SPEC.md, PLAN.md, or TICKET.md). If a Backend section exists, ask before overwriting / merging.

If the API contract is large, write it to magi/<num>-<slug>/openapi.yaml or magi/<num>-<slug>/schema.graphql and link from SPEC.md.

6. Optional: scaffold contract test

If the project has the relevant test framework (vitest+supertest, pytest+httpx, etc.), offer to create a contract test stub at tests/api/<feature-slug>.contract.test.ts (or the project's convention). Use the template in the reference. Selectors / payloads stay as TODOs.

Confirm with the user before creating files.

7. Stop and hand off

Show the user:

• Diff of SPEC.md (Backend section + linked schema files)
• Whether a contract-test stub was created
• Top 3 open questions

Recommend next step:

• /magi:tasks if SPEC is complete.
• /magi:web-frontend-spec / .infra.plan / .ci.spec if relevant.
• /magi:review-plan for multi-model review.

Argument parsing

• --sprint <num>-<slug> — explicit sprint folder.
• --api-style rest|graphql|grpc|trpc — skip detection.
• --scaffold-test — auto-create contract test stub.
• --no-scaffold — never create files outside the sprint dir.
• --openapi <path> — append to an existing OpenAPI file rather than create new.

Conventions

• Contract first: write the schema before discussing implementation.
• One Backend section per SPEC.md — iterate by editing in place.
• Backfill plans for populated tables are mandatory; do not let them slide.
• Authz matrix: never approve (none) for a mutating endpoint without explicit justification (e.g., webhook with HMAC verification).
• For very thin changes (e.g., adding a single optional field to an existing endpoint), tell the user this skill is overkill and recommend inline edits to SPEC.md.