---
name: tasks
description: Use whenever Tiber or origin/tiber is mentioned, including repository task tracking, EventCore publication conflicts, ambiguous pushes, tiber sync recovery, force-push safety, cross-worktree task-board coordination, setup, and task workflows.
---

# Tiber

Use Tiber for repository-local task boards backed by EventCore and eventcore-fs
on the shared Git `tiber` branch. Markdown task files are no longer persistent
state. Tiber is also the sole EventCore authority for pushed-CI recovery;
Development Discipline consumes its unresolved hold only for delivery gating.
The bundled launcher is `<plugin-root>/bin/tiber`; resolve `<plugin-root>`
relative to this skill file and prefer that launcher before probing `PATH`.

## Tool Selection

- Check for an installed `tiber` MCP server before using CLI commands.
- If the MCP tools are available, initialize the server with `tiber.init` only when setup is required, then use MCP tools for task reads and writes.
- If MCP tools are unavailable or fail to expose the needed operation, fall back to the bundled `tiber` CLI.
- Use `<plugin-root>/bin/tiber` before any `PATH` fallback.
- Offer `tiber install-bin --target-dir ~/.local/bin --dry-run` on setup or
  upgrade. Run `--apply` only after explicit user approval.
- For `tiber.ssh_authentication_failed` or a CLI that works while MCP reports a
  public-key authentication failure, check the current agent and shared Codex
  forwarding first. Installed portable MCP startup bootstraps a stable shared
  dispatcher automatically; activate a new bootstrap with a full Codex restart.
  Subsequent Tiber upgrades resolve the selected enabled installed launcher
  automatically even after old caches disappear, without installer reruns.
  Existing 1.1.x registrations need one migration using the marketplace installer
  or trusted current installed `scripts/configure-codex-mcp.py --apply`; a deleted
  old command cannot bootstrap itself. If the captured trusted Codex executable
  disappears, rebootstrap with the current trusted Codex. Then fully restart
  Codex from the current agent shell. Direct user-owned transports need `env_vars =
["SSH_AUTH_SOCK"]`; portable `mcp.json` cannot express it and `env` placeholders
  are literal. Preserve unmanaged registrations and unrelated environment rules.
  Do not save socket paths, copy keys, discover sockets, or broaden sandbox access
  to repair missing credentials. Socket rotation requires a new Codex process;
  HTTPS/unsigned repositories may leave the agent unset. See the plugin README.
- During setup, or after a Tiber MCP write/sync fails because Git cannot write
  refs, objects, signed commits, or push credentials from the Codex sandbox,
  call `tiber.codex_sandbox_setup` or run `tiber codex-sandbox --dry-run`.
  Use case-by-case approval for raw Git prefixes. Persist approval only when the
  harness can scope it to the exact Tiber-internal operation, not merely to a raw
  `git` prefix. Then retry the same structured MCP operation. Do not ask the
  user to rerun an equivalent Tiber CLI command manually as the normal recovery
  path, and do not recommend running the whole Tiber MCP server outside the
  sandbox unless the narrow Git permissions are insufficient.

## Rules

- Never mutate a repo merely because the plugin is installed or a session starts.
- Task reads and writes may run from a coordination-only primary checkout when
  Git reports it as bare but explicitly declares the source root through
  `core.worktree`; relative values resolve from the Git directory. Refuse a true
  bare repository or another context without an explicit worktree root with
  actionable repository-context guidance.
- Run `tiber init` only for explicit setup or when a requested task operation
  needs an initialized board. Legacy `.tasks` state is ignored rather than
  migrated; recreate any worthwhile historical tickets manually.
- Established-repository scaffold is a safety preflight, not file generation:
  verify the active executable hook-manager dispatcher, require pinned workflow
  and Tiber revisions with locked dependencies and only `contents: write`,
  target the repository's publication branch, and refuse generated publication
  when repository policy requires signing but no repository-owned automation
  supplies the key.
- Use CLI/MCP writes, not direct edits to the event store or authoritative Git
  ref. Legacy `.tasks` files and `order.md` are ignored history, not Tiber state.
- The dashboard can reorder backlog priority, which does not change capacity.
  It has no create or status-transition route. Admission writes go through CLI
  or stdio MCP tools and share the same capacity enforcement.
- Start a dashboard with `tiber dashboard serve --open` when the user wants it
  opened in a browser. An unconfigured launch selects an available localhost
  port and prints the complete URL. Repeated launches for the same project
  reuse its healthy server without opening another browser window. Use
  `--port <port>` only when the user requests a fixed port; a conflicting
  running instance or occupied requested port must be reported, not bypassed
  with a second project server.
- Invoke the `tiber:new-task` skill for quick backlog capture when the user
  wants a new task recorded from chat. That skill writes only through structured
  Tiber MCP tools and leaves the task in `backlog` unless the user explicitly
  asks to start work immediately.
- Before admitting a candidate, use `tiber.search` (CLI:
  `tiber search "<outcome terms>"`) across all statuses, including `done` and
  `abandoned`. Compare historical matches with the candidate. Combine genuinely
  overlapping work or reject a duplicate; create only when the candidate is
  materially distinct. Discovery alone does not create an obligation.
- When you open or discover a PR/MR for an in-progress task, update the task
  with `tiber update <ref> --pr-mr-url <url> --pr-mr-status <status>`, and keep
  `pr_mr_status` current as checks/review/merge state changes. Use stable
  lowercase statuses such as `draft`, `open`, `review-required`,
  `checks-pending`, `checks-passing`, `checks-failing`, `approved`, `merged`,
  `closed`, or `blocked`.
- Before actively working on an existing Tiber task, move it to `in-progress`
  with `tiber transition <ref> in-progress`; do not leave active work in the
  backlog as an informal reservation.
- When the development workflow requires a durable per-edit checkpoint, first
  persist it through the atomic Git-common-directory local owner defined by
  `development-workflow`. When task-board remote publication is independently
  authorized, append that successfully validated single-line `checkpoint-v1`
  record to the active task with `tiber.note.add` (CLI: `tiber note add`) as an
  optional mirror. If remote publication is not authorized, do not call a
  mutating Tiber operation. A mirror failure never makes the generic note API
  authoritative or invalidates the local record; retain it for handoff and
  retry only while publication remains authorized.
  Use the canonical `checkpoint-v1 ` compact-JSON wire form and deterministic
  tracked/untracked snapshot algorithm defined by the public
  `development-workflow` skill; that skill is the sole schema owner. Do not
  invent alternate keys, delimiters, hashes, or state-specific nullability.
  For the authoritative local owner, use the task-scoped lock and generation/predecessor
  compare-and-swap writer bundled with the public skill so a stale
  linked-worktree writer cannot replace a newer transition; do not synthesize a
  second filesystem implementation.
  Never put raw logs, credentials, or secrets in the note. On restart or
  handoff, read the authoritative local `.latest` owner first, then use
  `tiber.show` only to compare an authorized optional mirror or recover a
  retained publication failure. Reconcile the local record with Git and forge
  state before acting; a missing or behind mirror does not override valid local
  authority. Missing, malformed, non-atomic local, or mismatched authoritative
  evidence is a recovery hold, not
  permission to infer progress. These notes are evidence records; they do not
  emulate the unavailable native `workflow.*` scheduler.
- When `.tiber.toml` configures `[final_review].minimum_clean_reviews`, record
  every clean result and substantive finding through `tiber.review.record`.
  Explicit minima one and two are supported; preserve stronger configured minima.
  Scope receipts to independently reviewed behavior and verification dependencies
  so unrelated evidence is reusable only while both fingerprints remain current.
  Include the review identity, reviewer identity and type, exact Git pathspec
  scope, resolvable commit range, outcome, evidence, timestamp, current source
  fingerprint, verification-evidence scope, and its current fingerprint. Pass
  each pathspec as a separate array item or repeated CLI option; use `auto` for
  both fingerprints so Tiber computes them. Tiber resets the effective sequence
  on findings or changed scope/range/fingerprints. In policy mode, source and
  verification receipts must be committed: completion and trailer delivery
  recompute the v5 path manifests from one resolved full commit/tree identity,
  persist that immutable identity, and reject mutable or legacy-v4 evidence
  with condition-specific diagnostics. There is no runtime bypass; opting out
  requires an auditable repository configuration change.
  This requirement covers the source and verification paths selected by the
  review record, not the later Tiber review event itself. In local-only mode it
  makes a local commit repository-required; it never authorizes a push. If the
  user forbids committing while this policy is enabled, completion is blocked
  rather than replaced by a no-commit snapshot, empty post-review commit, or
  remote action.
- When `.tiber.toml` sets `[backlog].max_queued`, only `backlog` tasks count.
  The active `in-progress` task does not count. Creating, reopening, or moving
  work into `backlog` refuses once the limit is full across CLI and MCP.
- Treat `tiber.backlog_capacity_exceeded` as an admission decision, not a
  retryable sync failure. Do not create overflow, icebox, shadow, or hidden
  work. Require the user to replace a lower-value queued task, combine
  genuinely overlapping work, or reject the candidate.
- A confirmed expected stream-version mismatch is an optimistic-concurrency
  conflict: Tiber refreshes the authoritative branch and retries with the same
  invocation identity and inputs. An ambiguous publication outcome means durable
  publication was not confirmed or rejected; stop all mutations and use
  `tiber sync` to reconcile that exact pending invocation. Never force-push or
  rewrite `tiber`.
- Treat `close-from-trailers` as successful only when it synchronizes the
  authoritative board, resolves every `Closes:` line from the current `HEAD`
  commit, prints `closed <task-id>` for every requested task, and leaves every
  named task no longer open. A missing or invalid task, synchronization
  conflict, or publication/push failure must produce a specific diagnostic and
  a nonzero exit; never accept exit zero or empty output alone as closure
  evidence.
- Before any task-board health claim, run and name `tiber validate --fix`.
  Safe autofixes include misplaced claims and missing reciprocal links.
  Dangling refs and dependency cycles are report-and-resolve.
- `claim:` is valid only on in-progress tasks. Backlog claims are invalid, not
  reservations; use `tiber transition <ref> in-progress`.
- For repo integration, run only `tiber scaffold repo --dry-run`, show the
  planned hook/workflow, trailer workflow, and optional
  `justfile` additions, already-configured integrations, and conflicts, then
  stop until explicit approval. Evaluate hooks and workflows independently: an
  equivalent existing workflow suppresses only the generated
  workflow, and an equivalent existing hook suppresses only the generated hook.
  Preview any distinct missing integration. Legacy `.tasks`, `tasks`, and
  `tiber-coordination` state is ignored and never migrated automatically.
  Verify that Git's active executable `post-commit` hook
  dispatches the proposed Tiber snippet; a file that the active hook manager
  never invokes is not installed automation. Generated GitHub automation must
  pin both checkout and Tiber source revisions, install locked dependencies,
  target the repository's publication branch, declare only `contents: write`,
  and refuse signed-publication policy unless repository-owned automation
  supplies a signing key. Apply
  refuses ambiguous integration-file replacements; use `--replace-conflicts`
  only after the user explicitly chooses to replace every reported conflict.
  "No follow-up questions" is not approval to apply.

## Pushed-CI Incident Coordination

Use Tiber's semantic `tiber.ci_recovery.*` operations for pushed-CI recovery.
Development Discipline reads the resulting unresolved hold when deciding
whether delivery may proceed; it does not maintain a parallel incident.

## Commands

```shell
tiber init
tiber codex-sandbox --dry-run
tiber create "Task title"
tiber list
tiber list --status done
tiber search "outcome terms"
tiber show <task-ref>
tiber metadata <task-ref>
tiber next
tiber transition <task-ref> <status>
tiber review <task-ref> --review-id <id> --reviewer <identity> --reviewer-type <type> --scope '<git-pathspec>' [--scope '<git-pathspec>' ...] --commit-range <start>..<end> --outcome <clean|finding> --evidence <receipt> --timestamp <timestamp> --source-fingerprint auto --verification-scope '<evidence-pathspec>' [--verification-scope '<evidence-pathspec>' ...] --verification-fingerprint auto
tiber prioritize <task-ref> --before <task-ref>
tiber link <task-ref> blocks <task-ref>
tiber unlink <task-ref> blocks <task-ref>
tiber subtask add <task-ref> "Subtask title" --after s1,s2
tiber update <task-ref> --summary "..."
tiber update <task-ref> --pr-mr-url <url> --pr-mr-status checks-pending
tiber acceptance add <task-ref> "Observable condition"
tiber note add <task-ref> "Progress note"
tiber validate --fix
tiber close-from-trailers
tiber mcp stdio
tiber dashboard serve [--open] [--port <port>]
```

Pass multiline summary and context values directly through the structured CLI
or MCP update surface. Preserve actual line breaks and literal backslashes; do
not flatten text or substitute literal `\n` sequences. If Tiber rejects an
embedded heading reserved by the task schema, follow its recovery guidance to
demote or rename that heading.