Epiq

Epiq board workflow

• Use the epiq_* MCP tools for every board read and write — never the CLI, hand edits, or the state branch directly.
• Never edit the state branch directly. Don't check it out, don't write to its worktree, don't touch the event log or any file under it by hand or by script — go through the MCP for every read and write. The event log is the system of record: an edit made outside it bypasses validation and ordering, and can corrupt history in ways no later fix can undo.
• Keep the status column current as work progresses (move tickets along the board with correct status)
• Sync is on demand: call epiq_sync to pull or publish; nothing else does.
• Take an identity before your first write: provider/name (e.g. claude/peter), set with epiq_actor_assume. Reuse one from epiq_contributor_list — names are permanent. If other agents may be running, ask which name is free, rather than just picking one.
• Break work into small, reasonably scoped tickets.
• One MCP server per session — the name binds to the process; a restart forgets it. epiq_actor_assume binds the name to the server process it is called on, so two sessions on one server — or a session on the user's own instance — would sign every write with whichever name was assumed last, and the log would fold them into one contributor. Every session therefore needs a server process of its own.
• Keep tickets small; put a small follow-up on its existing ticket instead of a new one.
• Read a ticket's comments before starting.
• Picking up a ticket: assign yourself and move it to the in-progress lane. Ask before taking one assigned to someone else.
• Keep status, tags and description current; reuse existing tags.
• Comment on deviations, blockers, and the outcome when done.
• Prompt user for closing tickets and big decisions
• Park decisions that are the user's to make. A design fork, a change with blast radius beyond its ticket, anything you'd want a second opinion on - file a ticket tagged human-input-needed naming the options and the trade-offs, then carry on with whatever doesn't depend on the answer.
• Link commits by starting the subject with the ticket's ref from the MCP response — never derive the ref from the id.
• If a you decide to take a new approach, add a "fork" tag, and document the fork in a comment, also, update the description to reflect the new plan.
• Attachments are permanent in every clone (max 500 KB): only when a picture is needed, make sure images are cropped and compressed. An oversized image is permanent, for everybody — the same reason the text limits exist.
• Be concise. Titles, descriptions, and comments should be scannable, not essays.
• When a ticket is done, Document the outcome in a comment starting with "Solution:". Use that exact prefix as the comment's opening line.
• The git user is the sole author of every commit you write. Commit under the repo's configured user.name / user.email and nothing else: no Co-Authored-By: line, no Claude-Session: line, no 🤖 Generated with footer, and never an --author override naming Claude or a tool.
• Always rebase onto the target, never merge into it. Rebase the branch onto the target first, then integrate with a rebase merge — gh pr merge --rebase, never --merge. Main stays a flat sequence of ref-prefixed commits, which is what the commit↔ticket linking reads. A merge commit adds a subject carrying no ref and buries the branch's commits behind it.