From b0adb8d2b7c3d3f6cd879b669c02a06b9b264ba1 Mon Sep 17 00:00:00 2001 From: Victor Garcia Date: Fri, 2 Oct 2026 16:58:07 -0600 Subject: [PATCH 1/2] =?UTF-8?q?docs:=20AGENTS.md=20=E2=80=94=20layout,=20c?= =?UTF-8?q?heck=20commands,=20and=20the=20rules=20CI=20enforces?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..10eb1b7 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,58 @@ +# jig — agent instructions + +jig is a local-first software factory: one Go binary (control plane, worker, +CLI) plus a React UI that is committed pre-built and embedded. Read +`README.md` for the model (definition → run → job → attempt → phases) and +`docs/plans/` for the design records (KTD/R/U numbers cited in code and +commits). + +## Layout + +| Path | What | +|---|---| +| `cmd/jig/` | CLI entry points (`serve`, `worker`, `run`, `def`, `trigger`, `report`) | +| `internal/protocol/` | Definition schema and save-time validation | +| `internal/engine/` | Phase engine: chain, gates, repair edges, parallel group | +| `internal/controlplane/` | HTTP API, SQLite ledger, queue, reports | +| `internal/worker/` | Claims jobs, runs attempts, publishes via `gh` | +| `internal/runtime/` | Agent CLI adapters (`claudecode`, `codex`) | +| `migrations/` | SQLite migrations | +| `web/src/` | UI source; `web/dist/` is the committed build | +| `examples/definitions/` | Stock definitions, validated in CI | + +## Commands + +Go (from the repo root): + +| Command | Runs | +|---|---| +| `just check` | format-check, vet, boundary, definitions, test, build — what CI runs | +| `just test-race` | Race suite: controlplane, worker, engine, runtime | +| `just test` | `go test -timeout 5m ./...` | +| `go test ./internal/engine/ -run ` | One test while iterating | + +UI (from `web/`): + +| Command | Runs | +|---|---| +| `npm run typecheck` | `tsc -b` over app and vite config | +| `npm test` | vitest | +| `npm run build` | Rebuilds `web/dist/` | + +## Rules + +- **Commit the rebuilt bundle.** Any change under `web/src/` needs + `npm run build` and the resulting `web/dist/` committed; CI fails if the + rebuild differs from the tree. +- **Every module the UI imports must be in `web/package.json`.** This Mac has + a `~/node_modules` (including `@types/node`) that tsc and Node fall back + to, so a missing dependency passes locally and fails in CI. +- **The worker never imports the control plane** (`just boundary`, KTD1). +- **Definition changes are validated at save time.** A new definition field + or rule goes in `internal/protocol/definition.go` with a test, and the stock + definitions must still pass `just definitions`. +- **Parallel-group members are read-only and concurrent.** Anything that + dispatches or replays phases must not run a member outside the group. +- Work on a branch in a sibling worktree, open a PR, never push to `main`. +- `gofmt` everything; match the surrounding comment style, which explains + why and cites the plan ID. From 5ce8df89b04c9f211130349730b0c75a84287e27 Mon Sep 17 00:00:00 2001 From: Victor Garcia Date: Fri, 2 Oct 2026 17:14:12 -0600 Subject: [PATCH 2/2] docs: list jig start in AGENTS.md --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 10eb1b7..fd74c23 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -10,7 +10,7 @@ commits). | Path | What | |---|---| -| `cmd/jig/` | CLI entry points (`serve`, `worker`, `run`, `def`, `trigger`, `report`) | +| `cmd/jig/` | CLI entry points (`start`, `serve`, `worker`, `run`, `def`, `trigger`, `report`) | | `internal/protocol/` | Definition schema and save-time validation | | `internal/engine/` | Phase engine: chain, gates, repair edges, parallel group | | `internal/controlplane/` | HTTP API, SQLite ledger, queue, reports |