Linotype v4

v4 adds focus & optimise knobs, parallel workflow (queue, worktrees), and a clear agent contract (Orchestrator/Executor, _agent-rules.md + AGENTS.md).

What changed

Focus and optimise

Repos declare how strict agents should be:

• focus (scope discipline): loose

  standard

  strict

  • loose: broad slugs, cross-domain OK, 1 retry
  • standard: single-domain default, cross-domain if declared, 2 retries
  • strict: narrow slugs, single-domain enforced, 2 retries

• optimise (trade-off bias): speed

  cost

  quality (optional; default balanced)

Defined in docs/ai/_agent-rules.md. Independent of each other.

Parallel workflow

• Queue: optional stage between planning and doing. Move galleys to queue/ when ready for pickup; only move from queue to doing to claim work (first successful move wins).
• One branch per galley: e.g. slug/<galley-id>-<galley-name>.
• Worktrees: in parallel mode, one git worktree per active galley; each worktree checks out its galley branch.
• Conflict rule: one active galley per worktree; no two Executors work the same galley. Conflicts → stop, record in galley review.md.

Agent roles and contract

• Orchestrator: coordination, galley/slug shape and sequence, lifecycle moves, small fixes, review.
• Executor: run slugs (docs/code), run checks/tests, commit in required format, record in review artefacts. A galley has exactly one active Executor at a time.
• Authoritative rules: docs/ai/_agent-rules.md (Linotype contract).
• Repo adapter: AGENTS.md at repo root adapts Linotype to that repo (min reading order, commands, conventions). If it conflicts with _agent-rules.md, _agent-rules.md wins.

Galley lifecycle (with queue)

Stages: planning | queue | doing | review | done

• Move to queue/ when ready for handoff (optional).
• Move to doing/ when work starts (first slug in progress).
• Move to review/ when all slugs are done.
• CLI: cli/linotype galley move <galley-name> <stage>; handoff: cli/linotype exec opencode <galley> (generates executor brief from run-sheet).

Commit and output expectations

• After each slug: git commit -m "slug:<slug-name> done - <summary> #galley:<galley-name>"
• When galley complete: move to review/, then git commit -m "galley:<galley-name> ready for review - <summary>"

Migration from v3

1. Add docs/ai/_agent-rules.md from the Linotype skeleton; set focus and optionally optimise.
2. Add repo-root AGENTS.md from the skeleton template; fill in repo commands and conventions.
3. If using parallel work: add queue stage and document claiming and worktree strategy.
4. Switch workflow to galley-centric CLI: cli/linotype galley new, galley move, etc.
5. Align Cursor/Kiro (or other tools) to treat _agent-rules.md as authoritative and reference AGENTS.md for repo-specific behaviour.

See Galleys, Roles, and the skeleton’s docs/ai/_agent-rules.md and AGENTS.md for detail.