jig — AI-Native Dev Scaffold

The Codex 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.10.0). The legacy v2 branch is closed — don't route work to it. See docs/roadmap.md.
• Active specs: none in-flight (088 /jig:orient skill shipped + closed; 091 bug-fix repository-closure shipped + closed). 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; 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.
• 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 — spec 055 — cost ≈ orchestrator context × turns; delegate reads, keep the primer lean.
• Thin-orchestrator — spec 057 — turn count + peak context are the top cost 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.
• 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.
• 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.

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/AGENTS.md.template is the scaffold source — not this file.
• Hook commands use host-rendered paths (${CLAUDE_PLUGIN_ROOT}/hooks/scripts/... in Claude plugin mode, ${CODEX_PROJECT_DIR:-$PWD}/.codex/hooks/scripts/... in Codex scaffold mode); never rely on bare hook 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 AGENTS.md.