Skip to Content
Software FactoryTrackers & Knowledge

Trackers and Team Knowledge

New. Linear and Jira sync is behind the trackers feature flag; Notion knowledge is behind knowledge. Both are on by default. Turn one off in Settings → Feature flags or with shep settings flags disable trackers / shep settings flags disable knowledge.

A connection is an account Shep reads from: Linear or Jira for issues, Notion for documents. Each connection belongs to a space, so a work Jira and a personal Linear stay apart.

  • Trackers keep Linear or Jira issues in a Shep project as work items, and can write changes back.
  • Knowledge sources keep Notion pages or databases as team knowledge that agents in the space read when it fits their task.

Connect an account

ToolWhat you need
LinearA personal API key (Linear settings → Security & access)
JiraYour site URL (https://acme.atlassian.net), your account email and an API token from https://id.atlassian.com/manage-profile/security/api-tokens
NotionAn internal integration token (Notion → Settings → Connections → Develop or manage integrations). Then share each page or database you want Shep to read with that integration (••• → Connections → Add connection)

From the terminal:

shep connection add linear --name "Acme Linear" --space acme # prompts for the key shep connection add jira --name "Acme Jira" --space acme \ --site https://acme.atlassian.net --email me@acme.com # prompts for the token shep connection add notion --name "Acme Notion" --space acme # prompts for the token

The key is prompted for with hidden input, never passed as an argument. In scripts, put it in an environment variable and name the variable:

LINEAR_KEY=lin_api_… shep connection add linear --name CI --secret-env LINEAR_KEY

Shep checks the key against the service before saving it, stores it encrypted in its local database, and does not show it again. Without --space the connection belongs to the default space.

In the browser, open Connections in the sidebar (/connections), choose the tool, name the connection, pick the space, paste the key and press Connect.

CommandDoes
shep connection add <linear|jira|notion> -n <name> [-s <space>] [--site <url>] [--email <email>] [--secret-env <VAR>]Connect an account
shep connection lsList connections
shep connection test <connection>Check the credentials again
shep connection rm <connection>Remove a connection with its sync rules and knowledge sources. Work items it already synced stay

If a key stops working (revoked, expired), the connection shows Error with the service’s message and its rules or sources fail until it works again. Test / shep connection test re-checks it; the next clean run clears the error.

Tracker sync (Linear, Jira)

Add a sync rule

A rule says what to read and which Shep project it lands in:

  • Linear: a team key, such as ENG.
  • Jira: any JQL query, such as project = PAY AND type = Bug.
shep sync rule add acme-linear --project payments --scope ENG shep sync rule add acme-jira --project payments --scope "project = PAY AND type = Bug" --two-way --every 30

You need a project first (shep project new, see Projects). On the Connections page the same form sits under each connection.

OptionMeaning
-p, --project <project>Shep project slug or id (required)
-s, --scope <scope>Linear team key or Jira JQL query (required)
--two-wayAlso push Shep changes back to the tracker. Without it the rule only imports
--every <minutes>Minutes between automatic runs: 5 to 1440, default 15

Let it run

The Shep daemon runs every enabled rule on its interval. Each run asks the tracker only for issues changed since the last run. To run now: Sync now on the Connections page, or:

shep sync run # every enabled rule shep sync run <rule> # one rule

Each rule shows what its last run did: created, updated, pushed, conflicts and failed. A synced work item shows its issue key (for example ENG-42) next to its title, linking to the tracker.

CommandDoes
shep sync rule ls [connection]List rules with their last run
shep sync rule disable <rule>Stop the daemon running a rule (Pause in the browser)
shep sync rule enable <rule>Let the daemon run it again (Resume)
shep sync rule rm <rule>Remove a rule; synced work items stay

What is synced

FieldInto ShepBack to the tracker (two-way)
Title✓✓
Description✓ (Jira rich text becomes Markdown)✓
Status✓ (mapped to the project’s Backlog, Unstarted, Started, Completed or Cancelled state)✓
Priority✓✓

Comments, labels, assignees and attachments are not synced.

When a work item moves to a completed state in Shep, a two-way rule moves the Linear issue to the team’s first “completed” state, or takes the Jira transition into a done status.

When both sides changed. Shep remembers each field’s value at the last sync. If only the tracker changed a field, Shep takes it; if only Shep changed it, a two-way rule pushes it. If both changed the same field to different values, the tracker wins and the run counts a conflict.

Good to know:

  • Removing a rule or connection keeps the work items it synced.
  • A work item you delete in Shep is not imported again.
  • If the tracker rate-limits Shep, the run stops and says so; the next run picks up where it left off.

Team knowledge (Notion)

Add a source

A knowledge source is one Notion page with the pages under it (up to five levels deep), or one database (every row). Pass its link:

shep knowledge source add acme-notion \ --scope https://www.notion.so/acme/Engineering-handbook-0123456789abcdef0123456789abcdef shep knowledge source add acme-notion --scope <payments PRD database link> \ --product-line payments --every 240
OptionMeaning
--scope <link>Link or id of a Notion page or database shared with the integration (required)
-l, --product-line <line>Only repositories of this product line read it. Without it, the whole space does
--every <minutes>Minutes between automatic syncs: 15 to 1440, default 60

On the Connections page the same form sits under the Notion connection.

Sync

The daemon syncs each enabled source on its interval. A sync reads only the pages edited since the last one and drops pages that were deleted or unshared. To sync now: Sync now on the Connections page, or:

shep knowledge sync # every enabled source shep knowledge sync <source> # one source
CommandDoes
shep knowledge source lsList sources with their last sync (added, updated, removed, failed)
shep knowledge source disable <source> / enable <source>Stop or resume scheduled syncing
shep knowledge source rm <source>Remove a source and the documents it synced
shep knowledge ls [-s <space>]List a space’s knowledge documents
shep knowledge search "<task>" [-r <repo>]Show the passages an agent working in that repository would get for that task

The Project Memory page also lists each space’s documents, with links back to Notion.

What agents see

When an agent starts work in a repository, Shep splits the space’s documents into sections by heading, ranks the sections against the task by shared words, and adds the best ones — about 1,000 tokens — to the agent’s prompt under Team knowledge, each naming its page and section. Check what a task would pull in:

shep knowledge search "refund guest orders" --repo ~/src/pay

Limits and behaviour:

  • Shep only reads Notion; it never edits it.
  • Up to 500 pages per source and 100,000 characters per page are kept.
  • Images, files and embeds become placeholders; tables, lists, code and callouts keep their shape.
  • Ranking is by words, not meaning. A task phrased very differently from the page may not match it.

See also