Specs

A spec is a markdown file that defines a subsystem’s purpose, acceptance criteria, and constraints — the authoritative description of a piece of your codebase.

What a spec is

Specs are architectural landmarks, not tickets. You do not “complete” a spec and delete it. You complete tasks within a spec, and the spec remains as living documentation of the subsystem it describes.

Each spec lives in .jig/specs/ as a markdown file with a kebab-case name, such as auth-layer.md or user-dashboard.md.

Anatomy

# Feature: auth-layer

## Intent

Handles authentication and session management. Wraps Supabase Auth
with project-specific error handling and session refresh logic.

## Architecture

Token exchange flow: browser -> Supabase -> JWT stored in localStorage.
Refresh triggered on every API call via middleware.

## Key Files

- **src/auth/client.ts**: Auth client singleton
- **src/auth/middleware.ts**: Request signing and token refresh

## Patterns

All auth errors surface as AuthError (not generic Error) so callers
can distinguish them from network failures.

## Constraints

- Must not store raw tokens in cookies
- Must not add new external auth dependencies

## Acceptance Criteria

- [ ] User can log in with GitHub OAuth
- [ ] Session persists across browser refreshes
- [ ] Expired tokens refresh silently

Architectural layers

Specs belong to one of three layers:

Layer	Purpose	Examples
platform	Foundational infrastructure	database access, shared types, config
services	Business logic	domain services, data transformation
surface	User-facing	UI components, CLI commands, API endpoints

Assign a layer with --layer when creating: jig spec new auth-layer --layer platform.

Sub-specs

A spec can have a parent, making it a focused component under a broader architectural spec. Sub-specs appear indented under their parent in jig spec list and jig status.

jig spec new login-flow --parent auth-layer

Use sub-specs when a subsystem grows complex enough that its components benefit from separate intent and acceptance criteria.

Lifecycle

Specs do not have a status themselves — their tasks do. jig status aggregates task statuses to show how much work is done within each spec.

Archiving

When a spec’s work is complete or it is no longer relevant, archive it:

jig spec archive auth-layer

Archived specs are hidden from jig spec list and jig status by default but remain available for reference. They are not deleted.

CLI commands

See CLI Reference for full details on spec new, spec list, spec show, and spec archive.