Full-Stack Specification Writing Rules (Phase II)

Purpose

This skill enforces a strict spec-before-code discipline for full-stack web applications.
No frontend, backend, database, or authentication code may be written until a complete, approved specification exists.

This specification acts as a binding contract between:

• •Frontend (Next.js)
• •Backend (FastAPI)
• •Authentication (JWT / Better Auth)
• •Database (SQLModel + PostgreSQL)

Core Principles

1. Specification-First Mandate

• •NEVER write frontend or backend code before the specification is approved
• •All APIs, UI flows, auth behavior, and data models must be defined first
• •Specs must support multi-user, authenticated systems
• •The specification is the single source of truth

Mandatory Specification Structure (Phase II)

Every Phase-2 spec MUST contain all sections below.

A. Overview

• •Purpose: What problem does this system solve?
• •Scope: What is included and explicitly excluded?
• •Target Users: Authenticated users, roles (if any)
• •System Architecture:
  • •Frontend (Next.js App Router)
  • •Backend (FastAPI)
  • •Auth (JWT via Better Auth)
  • •Database (Neon PostgreSQL)

B. Functional Requirements

1. Frontend Requirements

• •Pages and routes (e.g. /login, /tasks)
• •UI states (loading, empty, error)
• •Auth flows (signup, signin, logout)
• •API interaction behavior
• •Client-side validation rules

2. Backend / API Requirements

For every endpoint, define:

• •HTTP method + path
• •Required headers (Authorization: Bearer JWT)
• •Request body schema
• •Response schema
• •Success status codes
• •Error status codes (401, 403, 404, 422, 500)

3. Authentication Requirements

• •JWT issuance behavior
• •Token expiry rules
• •Unauthorized request handling
• •User isolation rules (data ownership enforcement)

4. Data Requirements

• •Entities and fields
• •Field types and constraints
• •Ownership rules (user_id)
• •Indexing expectations

C. Non-Functional Requirements

• •Security (JWT validation, user isolation)
• •Performance expectations
• •API consistency rules
• •Error message clarity
• •Environment variable usage (no hardcoded secrets)

D. Constraints

Technical Constraints

• •Next.js App Router only
• •FastAPI + SQLModel only
• •PostgreSQL via Neon
• •JWT authentication mandatory

Architectural Constraints

• •Frontend NEVER directly accesses DB
• •Backend NEVER trusts user_id from URL without JWT validation
• •Stateless backend auth

E. Acceptance Criteria (CRITICAL)

Every feature must include:

• •✅ Happy-path scenario
• •❌ Unauthorized access scenario
• •❌ Cross-user access attempt
• •❌ Invalid payload scenario
• •Edge cases (empty data, duplicates, limits)

Acceptance criteria must be directly testable by:

• •API tests
• •Manual UI testing
• •Agent-based test-runner

Specification Lifecycle

Phase 1: Discovery

• •Identify frontend + backend + auth needs
• •Resolve ambiguity before writing spec

Phase 2: Drafting

• •Write all mandatory sections
• •Define contracts clearly between layers

Phase 3: Review

• •User approval required
• •No “TBD” allowed

Phase 4: Lock

• •Mark spec as APPROVED
• •Only then code generation may begin

Anti-Patterns (STRICTLY FORBIDDEN)

❌ Writing UI without API spec
❌ Writing API without auth rules
❌ Assuming frontend behavior
❌ Mixing implementation code in specs
❌ Skipping error cases
❌ Using vague language (“should”, “maybe”)

Quality Gate Checklist

Before approval, verify:

• • Frontend + Backend + Auth covered
• • Every API secured
• • User data isolation defined
• • JWT behavior specified
• • Acceptance criteria are testable
• • User explicitly approved spec

Usage

Invoke this skill when:

1. •Starting any Phase-2 feature
2. •Writing API, auth, or UI specifications
3. •Before generating backend or frontend code
4. •Preparing specs for agentic implementation

Success Criteria

A specification is complete when:

1. •Backend and frontend can be built independently
2. •No clarification is needed during coding
3. •Auth and security behavior is explicit
4. •Test-runner can validate it objectively
5. •User has approved it