jig — AI-Native Dev Scaffold

The Claude Code skill pack that scaffolds AI-native development practices. We dogfood the workflow we build.

Hot Cache

Always-loaded primer, kept lean per spec 055/057 (orchestrator context × turns is the cost). This is an index: each bold term is a one-line claim + link; full definitions live in docs/memory/glossary.md + the lexicon and expand on demand via /jig:explain <term>. Update via /jig:memory-sync.

Project codenames / active work

• jig = this skill pack repo (the plugin itself).
• Branch routing — main is the sole active line: 1.x and the 2.0 multi-host work both shipped here (latest tag v2.13.0). The legacy v2 branch is closed — don't route work to it. See docs/roadmap.md.
• Active specs: work has shipped through spec 113, plus 116 — the status board is the live source, always check it before picking up work. A few parked drafts remain (034 federation-tier, 062 refactor-workflow, 090 immutable-release-bytes, 105 durable-failure-quarantine); 083 lightweight-decision-records is IN_PROGRESS (083-08 Codex host-validation handoff open). Recent load-bearing closures are indexed under Key terms (leanness lens 109, first-class blockers 111, adversarial-register quarantine 110, ref-aware lifecycle + claim reservation 112, tri-host Copilot 113 — GitHub Copilot CLI is jig's 3rd committed host, plugin-only, full package parity; residuals in refinement-todo). Bug-fix repository closure — ADR-0037 (Accepted) / spec 091 — two marker-keyed closure gates on the bug lifecycle; JIG_BUG_CLOSURE_GATE=0. Per-slice invariants live in the status-board Notes column. Long-horizon-autonomy bridge (oh-my-cli follow-on): spec 106 — autonomy governance plane & identity separation (ADR-0051, Accepted) is built (see the Governance-plane term below); spec 105 — durable failure-quarantine jig-half (ADR-0050, Proposed) is still recorded, not built. servo halves live in ramboz/servo (servo specs 023/024/025, ADR-0029/0030) — not yet built. See docs/specs/README.md. Deferred → docs/refinement-todo.md.

Key terms (one-line index — full defs via /jig:explain <term>)

• Configurable docs root — ADR-0033 / spec 084 — layout.docs_root in scaffold.json (default docs); . = track-local adoption inside a larger repo; discovery sentinel-anchored; subtree push-mode refused. Read via _common/project_layout.py.
• Subagent permission — In this jig project, the user explicitly permits Codex to use subagents when they materially help implementation, review, reconciliation, or coordination work.
• Lifecycle-family spine — ADR-0023 — spec-workflow / bug-fix / refactor share one C1–C7 gated-evidence spine; extract to _common/lifecycle.py only at the third transition. PARKED — don't re-propose the servo pluggable-oracle boundary (ADR-0022 C5) without a real eval case / servo spec 006 / a built consumer.
• Closed-spec drift — ADR-0010 (supersedes ADR-0008) — closed records get ## Amendments; live prose corrected inline; new ADR for decision changes. Amending a record needs explicit owner approval (spec 102, issue #125): surface a canon-artifact conflict and stop; approving a behaviour ≠ authority to rewrite the record; read the whole criteria block before asserting a contradiction.
• Spec-gate model — ADR-0011 — jig-spec-gate.sh is a deliberateness gate on conventions.md, not human-only enforcement; real control is out-of-band.
• Security floor — ADR-0013 / spec 052 — 5-part scaffolded floor; defense-in-depth, not a firewall. Sibling Governance plane — ADR-0051 / spec 106 — scaffold-init scaffolds CODEOWNERS + protected-path CI + <docs>/governance.md and mirrors governance.PROTECTED_PATHS (self-referential) into scaffold.json.protected_paths (jig-boundary-change-warn soft-nudges in-boundary); inert until branch protection is armed (files, not server-side settings); autonomy precondition = merge-capability separation (not name), fail-safe when unknown, via governance.py identity-check (servo 023's signal).
• Review-evidence gate — ADR-0014 (spec 045) — transition gates REVIEWED/RECONCILED/DONE on recorded verdict artifacts; bypass JIG_REVIEW_EVIDENCE_GATE=0. Sibling Lifecycle entry gate — ADR-0044 / spec 098 — fail-open PostToolUse nudge on an out-of-lifecycle source edit (no live claim held by this checkout); reads .jig/spec-ref (slice + 098-04 bug=NNN arms) w/ a .gitignore/named-artifact boundary; JIG_ENTRY_GATE=0. Sibling Session git-freshness — ADR-0048 / spec 103 — fail-open SessionStart time-zero nudge: fetches (timeout-guarded, best-effort) the integration base, warns when HEAD is behind before a stale premise forms; smart-target resolution (non-own @{upstream} else origin/main→origin/master; own-remote guard = base drift, not own-branch advancement); JIG_GIT_FRESHNESS=0.
• Worktree-aware reservation — ADR-0015 / spec 051 — new routes on branch; off-main reserves via an ephemeral detached worktree at origin/main.
• Context-cost discipline / Thin-orchestrator — spec 055 + 057 — cost ≈ orchestrator context × turns (delegate reads, keep the primer lean); turn count + peak context are the top knobs; workflow.py session-plan dispatches.
• Token-usage tracking — spec 056 — usage.py report <spec> per-spec token/$ totals; price via ccusage, never hand-rolled.
• Slice-claim on working states — spec 049 / ADR-0045 — transition stamps claimed_by: on WORKING states, releases on the pickup queue + terminal; blank ≠ free. Sibling Ref-aware lifecycle checks + claim reservation — ADR-0058 / spec 112 — lifecycle checks consult sibling/remote refs, not just the checkout (the duplicate-work incident). Four classes: A already-integrated on origin/main → hard gate (land.py backstop + transition guard, keyed on branch-introduced ADRs not deps); B concurrent both-ends-IN_PROGRESS → extends ADR-0045 cross-ref via a refs/claims/<N> CAS reservation (identity read = hard block; CAS advisory; liveness = manual --release; fires on default and --push/--pr); C sequential re-do of work DONE-on-a-sibling (the reported incident) → sibling evidence-complete DONE read → halt-and-reconcile; D uncommitted/offline → advisory (DEFERRED). Shared _common/cross_ref_state.py + claim_ref.py; JIG_CROSSREF_GATE=0 / --reopen bypass. DEFERRED (refinement-todo): guard-family unification (trigger fired 112-05), Class-D advisory (112-06), landed-at anchor (112-07).
• Solo→team re-detection — spec 050 — re-evaluates the team signal; nudges to bootstrap people.md.
• Vocabulary barrier / lexicon — spec 065 / ADR-0021 — on-demand jargon via /jig:explain + lexicon, off the hot path.
• Status board — docs/specs/README.md, regenerated by workflow.py status-board; Notes column preserved + load-bearing.
• Recent review/posture closures — Leanness-review lens (ADR-0055 / spec 109): over-engineering / YAGNI check folded into the arch + reconciliation passes, no new gate — don't re-propose a standalone leanness gate. First-class blockers (ADR-0057 / spec 111): blocked_by: annotation on an actionable slice (not a lifecycle state) → board ## Blocked slices; distinct from DEFERRED/dependencies:. Adversarial-register quarantine (ADR-0056 / spec 110): the flaw-hunting register is bounded to the review passes (isolated reviewer subagents); outside a review, default collaborative and solution-forward. Use-case progress (ADR-0064, spec 116): read-only workflow.py progress [--summary], the one bounded exception to the PM out-of-scope line — a progress view, not a drift detector; don't grow it here.
• SPIDR, Vertical slice, Dumb zone, Reconciliation, Reframe (/jig:reframe — ADR-0024), Tier 0/1/2, Hot Cache, Research note (docs/research/R-NNN, ADR-0054) — see glossary / /jig:explain.

Key documents

Skills in this repo

The host surfaces every jig skill with its description each session — this primer does not re-list them (EngTip #23 / spec 076). Each skill's contract is its skills/<name>/SKILL.md; the per-tier roster is scaffold._TIER_SKILLS (mirrored in the glossary's Tier 0/1/2 entry). Skills with a .py helper: spec-workflow (workflow.py), independent-review (review.py), adr-workflow (adr.py), tdd-loop (tdd.py), slice-land (land.py), migrate (migrate.py), memory-sync (memory.py), code-health (health.py), bug-fix (bug.py); the rest are judgment-only. Explain any skill, term, or artifact with /jig:explain.

Host packaging details live in docs/architecture.md; Codex plugin packaging is built by scripts/build_codex_plugin.py (with --install-codex-agents for the explicit custom-agent TOML install step), and Copilot plugin packaging by scripts/build_copilot_plugin.py — all three hosts regenerated + drift-guarded by the single scripts/build_host_packages.py.

Session workflow

1. Check docs/specs/README.md + docs/bugs/README.md; route reported defects to bug-fix, then pick up the next READY_FOR_IMPLEMENTATION slice.
2. Implement (TDD). After the deliverable is on disk, run post-impl review — compliance + craft always, +arch/+code-health/+frame/+design iff the slice flags them. See docs/workflow.md + spec-workflow/SKILL.md.
3. Reconcile: deviation log, doc updates, reconciliation review.
4. /jig:memory-sync; update spec status + regenerate the status board.

Constraints for agents working on this repo

• Do not modify docs/conventions.md without explicit human approval.
• Reviewer subagent is read-only (Read / Glob / Grep) — it cannot write to memory.
• templates/CLAUDE.md.template is the scaffold source — not this file.
• Hook commands use bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/… (never bare names); all hooks use Python 3 for JSON (never jq).
• ADRs → docs/decisions/adr-NNNN-<slug>.md (ADR-0004); slices → docs/specs/NNN-<slug>/slice-NN-<short>.md (spec 018, sibling files; spec.md is the overview).
• When a slice closes a spec, compress its Active-specs entry (spec 025-01); load-bearing per-slice invariants migrate to the status board Notes column, not CLAUDE.md.