Skip to content
Jig

Using Jig with Claude Code

What you’ll learn: How jig run invokes Claude Code, what Claude Code sees, how to read run output, and how to commit completed work.

Prerequisites: Jig initialized, at least one decomposed spec. See Your First Project if you’re starting fresh.

How jig run works

jig run <spec> <task> generates a structured prompt from the task YAML and passes it to Claude Code via claude -p. Claude Code executes in your project directory with full filesystem access.

Terminal window
$ jig run user-auth auth-api-routes


Running task "auth-api-routes" for spec "user-auth"...


Run 2 succeeded (41.2s)
Saved to .jig/runs/user-auth/auth-api-routes-run-2.yaml

The prompt Claude Code receives contains:

  • The spec’s intent and acceptance criteria
  • The task’s objective, file scope, guardrails, and verification gates
  • Any context bundle contents referenced in the task

What Claude Code is constrained to

Each task has a file_scope list. Claude Code is instructed to modify only those files. This prevents unintended changes spreading across unrelated parts of the codebase.

file_scope:
  - src/routes/auth.ts
  - src/middleware/auth.ts
  - tests/auth.test.ts

If you need Claude Code to touch a different file, add it to file_scope before running:

.jig/tasks/user-auth/auth-api-routes.yaml
# Edit the task YAML directly

Reading run output

After a run, the result is saved to .jig/runs/<spec>/<task>-run-N.yaml:

id: auth-api-routes-run-2
task_id: auth-api-routes
result: success
duration: 41200
output: |
  Added POST /auth/signin and /auth/signup to src/routes/auth.ts.
  Signup hashes password with bcrypt (cost 10).
  Signin validates hash, returns 401 on mismatch.
  Tests: 6 passed, 0 failed.
verification_results: []
timestamp: 2026-03-03T14:22:11.000Z

Inspect any run:

Terminal window
$ cat .jig/runs/user-auth/auth-api-routes-run-2.yaml

Mark the task done

After reviewing the output and running your own verification, close the task:

Terminal window
$ jig task done user-auth/auth-api-routes \
  --notes "Changed: src/routes/auth.ts (signup + signin endpoints, bcrypt hashing, 401 on bad creds). Decisions: bcrypt cost 10 matches existing user profile hashing. Watch: requires setup-auth-schema migration to have run."

When a run fails

If the run exits non-zero, the task is marked failed automatically. Read what went wrong:

Terminal window
$ cat .jig/runs/user-auth/auth-api-routes-run-1.yaml | grep -A5 "result:"
result: failed
output: |
  Error: Cannot find module 'bcryptjs'
  ...

Fix the underlying issue (in this case, install the dependency), then re-run:

Terminal window
$ bun add bcryptjs
$ jig run user-auth auth-api-routes

Check what’s next

After marking a task done, its dependents become available:

Terminal window
$ jig next


Ready tasks (1):
  user-auth/auth-ui    [setup-auth-schema: passed, auth-api-routes: passed]

Commit workflow

Use a structured commit format so the audit trail connects git history to Jig tasks:

Terminal window
git add src/routes/auth.ts src/middleware/auth.ts tests/auth.test.ts
git commit -m "feat: add signup and signin endpoints [user-auth/auth-api-routes]


Changed: src/routes/auth.ts (POST /auth/signup, POST /auth/signin)
Decisions: bcrypt cost 10 to match existing profile hashing
Watch: requires 001_users migration before deploy
Verification: bun test (6 passed), bun run build (pass)"

The [spec/task] tag in the subject line makes it easy to trace any commit back to its originating task.

Skipping jig run for manual work

You don’t have to use jig run for every task. If you implement something yourself:

Terminal window
$ jig task start user-auth/auth-ui
# ... implement manually ...
$ jig task done user-auth/auth-ui --notes "Implemented SignInForm and SignUpForm components."

jig run is most useful for tasks where you want Claude Code to handle the full implementation autonomously. Manual tasks still get notes and status tracking.

Next: Using Jig in Claude.ai to architect and review from a conversation.