Teamboard

Team Board (shared claims + shared item memory)

Trigger phrases: "team board", "who is working on", "claim", "take this item", "pick up a task", "sprint item", "release the item", "hand the item over", "is anyone on", "board", "of us are working", "stepping on each other", "who is doing what", "who else is working"

The problem this closes

Every teammate runs Crewforth locally. docs/PLAN.md and docs/SESSION_STATE.md are gitignored, so the fact that Ali started item #1 two hours ago exists nowhere the other sessions can see. Two people start the same item; a blocked item gets picked up before its dependency lands; whoever inherits half-finished work rebuilds the context from scratch. The board makes those three facts shared.

The engine (all commands go through it)

bash .claude/hooks/board.sh — status · show · claim · done [note] · drop · note · add [deps] [external] · init · sync. Never hand-edit the board; every write must go through the engine or it loses its atomicity.

Why a claim is a real lock, not a convention

The board lives on a git ref (refs/crew/board), not in the worktree. A claim is a commit pushed to that ref, and git push is fast-forward-only: when two people claim the same item from the same base, one push is rejected and that session re-reads the board and refuses. This is an atomic compare-and-swap with no server, no token and no daemon. The engine builds its commits with git plumbing, so claiming never touches your working tree, index, branch or stash — you can claim mid-feature with dirty files.

Off by default; on when a team asks for it

A repo that never ran init has no board and no gates — no claim, no commit gate, no edit gate, nothing at session start. Solo work is unchanged, and so is every project that installed Crewforth before this existed. Do not create a board because a repo merely has more than one contributor; create one when the user says the team keeps colliding. Creating one, choosing between its three levels and the ref-namespace fallback: references/setup.md — one person runs it once, and everybody else configures nothing.

Already have a board and want it out of the way? /crew-board off (add --global for every repo) releases all three gates and leaves the board itself intact; /crew-board on restores it. CREW_NO_BOARD=1 does the same for one session. This half stays here on purpose: someone a gate has just stopped needs the answer without opening a second file.

The rules

1. Claim before you touch code. claim fails if someone else holds it, if it is done, or if a

dependency is unfinished — with the reason and the list of what is claimable. Do not argue with a refusal; take a free item.

1. Two gates, not one, and the early one is the point. The first file edit is refused while you hold no item

(guard-write.sh) — unclaimed work is caught at minute one, not at commit time after an afternoon of it. The commit then has to carry [#] for an item you hold and that is in_progress, or [chore] for work belonging to no item. In a repo with no board neither gate exists. CREW_NO_BOARD=1 disables both for a session; say so out loud if you set it.

1. Never release silently. drop REQUIRES a handover note, because the whole cost of a handover is the

context the next person does not have: where exactly it stands, which files, and why the rejected approach was rejected. done takes a completion note (what shipped, commit/PR).

1. Never steal a stale claim. A claim with no heartbeat for stale_hours (default 8) is reported as STALE.

Stale means ask the owner, not take it. Surface it to the user and let them decide.

1. Read before you plan. At session start the board summary is injected automatically. Before proposing what

to work on, run status — recommending an item somebody already holds is the failure this exists to prevent.

Redaction — the board is shared

Everything written here is pushed to a remote the whole team reads. handoff's … rule applies unchanged: strip secrets, tokens, credentials and personal notes, leave [redacted], and point at where a value lives (env var, secret manager, the person to ask) rather than the value.

Filling the board

Items come from either direction, and both end at add:

• From a plan: crew-planner + spec-planning produce docs/PLAN.md with measurable acceptance criteria and

a dependency order; each task becomes one add . Keep the plan's dependency edges — they are what makes claim able to refuse blocked work.

• By hand: the user dictates the items.

Tracker link (honest boundary)

Teams use Jira, Trello, Linear, GitHub Issues or nothing, so Crewforth binds to none of them. An item carries an optional external: field, which is a link and nothing more — no sync, no import, no write-back. A team that wants two-way sync writes an executable .crew/board-adapter.sh answering two verbs: import (emit ||| lines to be fed to add) and export (push the state outward). Crewforth ships no adapter; do not claim integration Crewforth does not have.

When the remote is unreachable

Claims stay local and are labelled UNSHARED — meaning the team cannot see them, so the lock is not in force. Say that plainly rather than reporting success, and re-run sync once the network is back.

DoD

• Work started only on an item held by this user; the board shows it in_progress.
• An item left for any reason carries a handover note a stranger could resume from.
• done recorded with what shipped, and the dependents it unblocked named to the user.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: crewforth
• Source: crewforth/crewforth
• License: MIT
• Homepage: https://crewforth.com/

Install and usage instructions live in the source repository linked above.