Docs

Quick start

You need Node.js 22 or later and a monday.com board with a Jira link column. The README has full detail on each setting.

  1. Install the package in your project:

    npm install @delvera-ai/plumbline
  2. Create a config file named plumbline.env with your own values. Each line is KEY=value, and lines starting with # are comments.

    # plumbline.env: placeholder values only
    MONDAY_TOKEN=...
    MONDAY_BOARD_ID=...
    MONDAY_STATUS_COLUMN=status
    MONDAY_DATE_COLUMN=date4
    MONDAY_LINK_COLUMN=link
    MONDAY_STATUS_CLASSES={"Done":"done","Working on it":"active","Not started":"not_started"}
    JIRA_BASE_URL=https://example.atlassian.net
    JIRA_EMAIL=you@example.com
    JIRA_TOKEN=...

    The file holds tokens, so keep it out of version control and make it readable only by you.

  3. Print a drift report with plumbline audit --config FILE, where FILE is your config file:

    npx @delvera-ai/plumbline audit --config plumbline.env
  4. Add the MCP server to your assistant with plumbline mcp. This example registers it with Claude Code. Replace each placeholder with your own values:

    claude mcp add --transport stdio \
      --env MONDAY_TOKEN=... \
      --env MONDAY_BOARD_ID=... \
      --env MONDAY_STATUS_COLUMN=status \
      --env MONDAY_DATE_COLUMN=date4 \
      --env MONDAY_LINK_COLUMN=link \
      --env 'MONDAY_STATUS_CLASSES={"Done":"done","Working on it":"active","Not started":"not_started"}' \
      --env JIRA_BASE_URL=https://example.atlassian.net \
      --env JIRA_EMAIL=you@example.com \
      --env JIRA_TOKEN=... \
      plumbline -- npx -y @delvera-ai/plumbline mcp
  5. Start your assistant and ask it to run find_drift.

Drift rules

Plumbline compares monday.com plan items with their linked Jira issues and reports each mismatch as a finding. The examples below use fictional plan items and issue keys.

PLAN_DONE_WORK_OPEN

Fires when a plan item is marked done but at least one of its linked Jira issues is still open. Severity is high.

Example: Plan item PLAN-7 "Night-mode palette" is marked done, but linked issue DEMO-12 is still In Progress, so Plumbline reports PLAN-7 with DEMO-12 as evidence.

WORK_DONE_PLAN_OPEN

Fires when every linked Jira issue is done but the plan item is not marked done. An item with no linked issues does not fire this rule. Severity is medium.

Example: Plan item PLAN-9 "Export to CSV" is still Working on it, but its only linked issue DEMO-31 is Done, so Plumbline reports the mismatch.

DUE_SOON_NO_ACTIVITY

Fires when a plan item that is not done is due within seven days, or is already overdue, and none of its open linked issues has changed in the last seven days. Items with no due date, or with no open linked issues, do not fire this rule. Severity is high.

Example: Plan item PLAN-4 "Billing reminders" is due 2026-11-14. Its open issues DEMO-18 and DEMO-19 were last updated on 2026-10-30, so Plumbline reports that no work has moved ahead of the deadline.

DATE_CONFLICT

Fires when a plan item has a due date and one or more of its linked Jira issues is due on a later day. Dates are compared by UTC calendar day. Items with no due date, and issues with no due date, do not fire this rule. Severity is medium.

Example: Plan item PLAN-2 "Onboarding emails" is due 2026-11-20, but its linked issue DEMO-40 is due 2026-11-27, so Plumbline reports DEMO-40 as due after its plan item.

NOT_LINKED

Fires when a plan item is active but has no Jira keys at all. Done and not-started items do not fire this rule. Severity is low.

Example: Plan item PLAN-6 "Team calendar sync" is In Progress, but nobody has added a Jira key to it, so Plumbline reports that it has no linked work.

KEY_NOT_FOUND

Fires when a plan item names one or more Jira keys that do not match any issue Plumbline was given. Severity is medium.

Example: Plan item PLAN-8 "Audit log export" names DEMO-50 and DEMO-51, but only DEMO-50 is in the supplied issues, so Plumbline reports DEMO-51 as not found.

Tools

Plumbline exposes these tools to the assistant.

find_drift
Returns every drift finding for the plan.
explain_item
Takes a plan item id and returns that item, its linked Jira issues and its findings.

Board and issue text is untrusted data, so the assistant should report that text rather than follow any instructions in it.

Settings

Plumbline is configured with these environment variables.

The server reads these once at startup and stops with a message naming any missing or invalid setting.

Read-only tokens

Give Plumbline tokens that cannot write.

Plumbline enforces read-only requests in code. A token that cannot write is a second line of defence if that check is ever bypassed.

Trust notes

For full detail on each setting, see the README.