jig

A Claude Code and Codex workflow layer that scaffolds AI-native development practices into new projects.

jig (noun): a tool that guides other tools to work accurately and consistently.

Why jig

Two years of AI-assisted coding leave the same scars on every non-trivial
project: LLMs refactor whole layers before anything works end-to-end, "done"
drifts because no acceptance criteria are written down, implementers grade
their own homework, and mega-packs burn the context budget before your work
loads. jig encodes the workflow that prevents each one — so you don't
rediscover it session by session.

→ The jig philosophy — the full why: the named
scars, how jig thinks, and the honest objections.

What it does

Idea → Spec → Vertical slice → Implementation → Independent review → Reconciliation → Done

jig installs a focused, opinionated workflow layer into your project:

• Spec-driven development — SPIDR-split vertical slices, each with its own
  Definition of Done.
• Multi-perspective review — a fresh, read-only reviewer checks every
  slice against its spec (compliance), plus a craft pass and an on-demand
  architecture pass.
• Memory layer — cross-session continuity via hot cache + deep storage +
  inbox.
• Deterministic gates — hooks enforce what must happen; skills carry
  judgment.

A fixed, opinionated set — 7 Tier 0 skills at the floor and 13 more on by
default (Tier 1) — not a hundred-skill marketplace. For the full picture, see
product-vision.md (vision, target users, principles)
and architecture.md (mechanics).

Principles jig encodes

The convictions behind the mechanisms — each one wired into something concrete,
not left as advice:

• The harness matters more than the model. jig is a harness: the
  instructions an agent reads, the tools it can run, the feedback loops that
  correct it, the isolation boundaries that contain it. Swapping models won't
  close a workflow gap — the scaffold does.
• Guardrails, not guidelines. What must happen is enforced mechanically by
  deterministic gates: hooks for immediate local checks (secret scanning,
  spec-file gates) and workflow transitions for lifecycle evidence
  (review-evidence gates, reconciliation artifacts). What takes judgment
  lives in skills. The line between a deterministic gate and an advisory nudge
  is drawn on purpose.
• The context window is working memory, not a storage buffer. Irrelevant
  context degrades reasoning, so jig keeps a lean hot cache, loads deeper docs
  on demand, and delegates file-heavy reading to subagents that return only a
  summary.
• Designed to reduce token cost. Beyond keeping context lean for quality,
  jig is built to keep token usage — and the bill — down: lean context,
  file-heavy reading delegated to subagents, tight output. It also measures its
  own spend rather than guessing at it.
• Review is the bottleneck. Agents produce faster than review capacity
  grows, so jig won't let implementers grade their own homework: a fresh,
  read-only reviewer checks every slice against its spec, and the verdicts are
  durable artifacts that gate the next state.
• Specs and docs are code, and they ship in slices. Specs, ADRs, and the
  memory layer are version-controlled and reconciled before a slice lands — so
  "done" never drifts, and work arrives as vertical slices instead of one big-bang
  mega-commit.

These are the outward-facing worldview; several are also load-bearing build
rules jig holds itself to, spec by spec — see
product-vision § Design principles
for the operational detail.

jig now ships one development experience across Claude Code and Codex: the same
workflow model, rendered into host-native files by the host-adapter layer
(spec 033). The next big
horizon is coordination across a multi-repo workspace (a federation tier —
spec 034).

Start here

New to jig? Read the
adoption & readiness guide first — who jig is
for, what your repo needs, and your first 30 minutes.

Install

Claude plugin

/plugin marketplace add ramboz/jig
/plugin install jig@jig

Claude scaffold

git clone https://github.com/ramboz/jig.git
python3 jig/hosts/claude/skills/scaffold-init/scaffold.py --in-repo <your-project>

Codex plugin

codex plugin marketplace add ramboz/jig
codex plugin add jig@jig

Codex scaffold

git clone https://github.com/ramboz/jig.git
python3 jig/hosts/codex/plugins/jig/skills/scaffold-init/scaffold.py --host codex --in-repo <your-project>

Which pair do I want? The two scaffold recipes are self-contained —
they copy jig's machinery into your project, so it works with no plugin
installed. The two plugin recipes leave the machinery
in the plugin and keep your repo lean — that's the default when jig runs as an
installed plugin. See
ADR-0041.

Project setup

Once installed, open a new project directory in Claude Code and say:

"Set up this project for AI-native development"

The scaffold-init skill will run and produce the docs/ scaffolding.

Copy-paste prompts live in the prompt cookbook, in
the order you run them: scaffold the repo once, then repeat the idea-to-landed
loop for every feature.

Extension points

Bring your own depth; jig provides the floor.

A few jig skills — pr-review, arch-review, contracts, security-review,
code-health, explain, vision-elicitation — ship as lightweight baselines
that defer to a richer user-installed skill in the
same category when one is present. The deferral is category-based, not
name-specific, so your own reviewer skill wins automatically, with no
configuration. jig stays opinionated about workflow and out of the way of
the judgment skills you've already invested in. Detail:
product-vision § Design principles.

Verifying a host install

Each host is verified in its own environment — one host's check does not
prove the other installs and runs:

• Claude: python3 scripts/verify_install.py confirms the install
  footprint, and python3 scripts/build_release_zip.py --host claude --smoke-test <zip> exercises the committed hosts/claude package. Spec
  061-06 owns the full Claude install-verification slice.
• Codex: python3 scripts/codex_install_smoke.py validates the committed
  hosts/codex package and probes a live Codex CLI when present. Spec 061-07
  owns the full Codex install-verification slice.

From source (contributors)

See CONTRIBUTING.md for the local-marketplace
workflow used during development.

Repository structure (for contributors)

Three peers: the canonical source root, the committed hosts/claude
package, and the committed hosts/codex package. The two host packages are
committed, source-derived build outputs — kept fresh by the drift guard
(python3 scripts/build_host_packages.py [--check]) and NOT hand-edited.
The host packages have different internal shapes: Claude is a flat
plugin (.claude-plugin/plugin.json at the package root) while Codex is
marketplace-wrapped (hosts/codex/.agents/plugins/marketplace.json +
hosts/codex/plugins/jig/...).

# Canonical source root (dev tooling + the tree the host packages build from):
.claude-plugin/plugin.json       # Claude plugin source manifest
.claude-plugin/marketplace.json  # remote-install pointer → ./hosts/claude
.agents/plugins/marketplace.json # Codex remote-install pointer → ./hosts/codex/plugins/jig
.codex-plugin/plugin.json        # Codex plugin source manifest
skills/                          # Skill definitions (SKILL.md per skill)
agents/                          # Subagent definitions
hooks/                           # Hook configuration + Python scripts
scripts/                         # Top-level dev scripts (verify-install, …)
templates/                       # Source templates scaffold-init generates from
docs/                            # Dev docs for jig itself (dogfooded workflow)
  specs/                         # Specs for jig's own features
  memory/                        # jig's own memory layer
  decisions/                     # Architectural decisions (ADRs)

# Committed, drift-guarded host packages (built from source; NOT hand-edited):
hosts/
  claude/                        # COMMITTED flat Claude plugin package
  codex/                         # COMMITTED marketplace-wrapped Codex package
    .agents/plugins/marketplace.json
    plugins/jig/                 # the Codex plugin tree
dist/                            # gitignored — host-explicit release ZIPS ONLY

Contributing

Read CONTRIBUTING.md for the local install + verify flow,
then docs/workflow.md for the spec lifecycle. Every
change to jig starts with a spec. PRs squash-merge with conventional-commit
titles (feat(scope): … / fix(scope): …); the pr-title.yml workflow
enforces the shape, and CONTRIBUTING § Releasing has the version-bump effect of
each prefix.

How jig compares against other AI-native playbooks — and where each known gap
is owned — lives in
CONTRIBUTING § Comparison and gap response.

Status

Tier 0 and Tier 1 are complete — all 20 skills, 3 subagents, and the jig hooks
ship today, and jig is dogfooded on its own spec lifecycle. For live per-slice
state, see the status board.

Supported today: Claude Code and Codex in scaffold and plugin shapes from
the shared source tree. Codex role prompts are bundled as prompt source, rendered
to TOML for scaffold mode, and installable for plugin users via the explicit
Codex agent helper; plugin-native Codex custom-agent discovery remains the
tracked follow-up in spec 033.