Skip to content
Jig

Your First Project

What you’ll learn: How to create a spec, decompose it into tasks, run one with Claude Code, file a bug, and close the loop.

Prerequisites: Jig installed and initialized. If not, follow Getting Started first.

1. Check your project status

After jig init, your .jig/ directory is ready. Run jig status to see the current state:

Terminal window
$ jig status


No specs yet. Add your first with: jig spec new <name>

2. Create a spec

Specs are markdown files that describe a feature. Create one:

Terminal window
$ jig spec new user-auth

This opens .jig/specs/user-auth.md with a template. Fill in the intent and acceptance criteria:

## Intent
Add email/password authentication so users can sign in and their data persists across sessions.


## Acceptance Criteria
- [ ] User can sign up with email and password
- [ ] User can sign in with valid credentials
- [ ] Invalid credentials return a clear error message
- [ ] Authenticated state persists on page refresh

3. Decompose the spec into tasks

Terminal window
$ jig decompose user-auth


Decomposing spec "user-auth"...


Proposed tasks:
  1. setup-auth-schema    — Add users table and auth schema
  2. auth-api-routes      — POST /auth/signup and /auth/signin endpoints
  3. auth-ui              — Sign in / sign up form components
  4. session-persistence  — Store and restore auth token from localStorage


Write these tasks? [y/N] y


Created 4 tasks in .jig/tasks/user-auth/

4. See what’s ready

Terminal window
$ jig next


Ready tasks (4):
  user-auth/setup-auth-schema     [no dependencies]
  user-auth/auth-api-routes       [depends on: setup-auth-schema]
  user-auth/auth-ui               [depends on: auth-api-routes]
  user-auth/session-persistence   [depends on: auth-ui]

5. Run the first task

Start the task and execute it with Claude Code:

Terminal window
$ jig task start user-auth/setup-auth-schema
$ jig run user-auth setup-auth-schema


Running task "setup-auth-schema" for spec "user-auth"...


Run 1 succeeded (23.4s)
Saved to .jig/runs/user-auth/setup-auth-schema-run-1.yaml

6. Mark it done and add notes

Terminal window
$ jig task done user-auth/setup-auth-schema \
  --notes "Changed: migrations/001_users.sql (added users table, bcrypt hash column). Decisions: used uuid primary key. Watch: migration must run before auth-api-routes."

7. File a bug during testing

While testing, you notice sign-in returns HTTP 200 even on wrong passwords. File it immediately:

Terminal window
$ jig task fail user-auth/auth-api-routes \
  --notes "Blocked by: signin endpoint returns 200 on invalid credentials instead of 401. Tried: checked route handler — status code hardcoded. Next: fix status code logic in src/routes/auth.ts."

Or capture it as a standalone bug (from CLI or Claude.ai):

Terminal window
$ jig bug "Signin returns 200 on wrong password — should be 401"

8. Check overall progress

Terminal window
$ jig status


user-auth
  setup-auth-schema     passed
  auth-api-routes       failed
  auth-ui               new
  session-persistence   new

The cycle

Spec → Decompose → Run → Review → Mark done/failed → Iterate.

Each jig task done --notes builds an audit trail. Each jig task fail --notes documents the blocker so the next run starts with full context.

Next: Using Jig with Claude Code to run tasks from your terminal using jig run.