pm-claude-skills/templates/pm-sprint-agent/connectors/README.md

Connectors — Setup Guide

This folder contains the connector configurations for the PM Sprint Agent. Connectors provide governed access to your team's data sources — they are how the agent reaches Linear, Jira, Slack, and other systems without holding credentials in prompts.

What's in this folder

• linear.example.json — Linear connector configuration template
• jira.example.json — Jira connector configuration template (use this if your team uses Jira)
• slack.example.json — Slack connector for posting summaries (coming soon)

How to set up a connector

You only need to set up the connector for the ticketing system your team uses. Skip the others.

Linear setup (5 minutes)

1. Generate a Linear API key:

   • Go to https://linear.app/settings/account/security
   • Click "Create Key"
   • Copy the key (starts with lin_api_)

2. Set the environment variable:

   export LINEAR_API_KEY='lin_api_xxxxxxxxxxxxxxxxxxxxxxxx'
   

   To make this permanent, add the line to your ~/.zshrc or ~/.bashrc.

3. Find your team ID:

   curl -H "Authorization: $LINEAR_API_KEY" \
     https://api.linear.app/graphql \
     -d '{"query": "{ teams { nodes { id name } } }"}'
   

   You'll get a JSON response with all your teams and their IDs.

4. Copy the example config and customise:

   cp linear.example.json linear.json
   

   Edit linear.json and update:

   • workspace_url — your Linear workspace URL
   • team_id — the team ID from step 3

5. Test:

   cd ../  # back to pm-sprint-agent root
   bash orchestrate.sh --dry-run --sprint-goal "test"
   

Jira setup (5 minutes)

1. Generate a Jira API token:

   • Go to https://id.atlassian.com/manage-profile/security/api-tokens
   • Click "Create API token"
   • Give it a label (e.g., "PM Sprint Agent")
   • Copy the token

2. Set environment variables:

   export JIRA_EMAIL='you@yourcompany.com'
   export JIRA_API_TOKEN='ATATT3xFfGF0...'
   

3. Find your project key and board ID:

   • Project key: visible in any issue URL (e.g., "PROJ" from your-domain.atlassian.net/browse/PROJ-123)
   • Board ID: navigate to your board, the URL contains boards/{ID} (e.g., 123)

4. Copy the example config and customise:

   cp jira.example.json jira.json
   

   Edit jira.json and update:

   • instance_url — your Atlassian instance URL
   • project_key — your project key from step 3
   • board_id — your board ID from step 3

5. Test:

   cd ../
   bash orchestrate.sh --dry-run --sprint-goal "test"
   

Building a connector for another system

If your team uses a ticketing system that's not in this folder (Shortcut, Asana, ClickUp, GitHub Issues), you can build a connector by following the same pattern.

A connector needs three things:

1. A configuration file ({name}.json) defining the data source URL, credentials, and available operations
2. An API client that the orchestration script can call to fetch data
3. A mapping from the source's data model to the standard fields the agent expects (issue ID, title, story points, status, assignee, dependencies)

The cleanest place to start is to copy linear.example.json or jira.example.json and modify it for your system.

If you build a connector for a new system, consider raising a PR back to the main pm-claude-skills repo so others can use it.

Security notes

Credentials live in environment variables, not in the JSON files. The connector configs reference environment variable names, not the actual credentials. This means you can commit your linear.json or jira.json to source control without leaking credentials — but make sure your LINEAR_API_KEY or JIRA_API_TOKEN are stored securely (use a password manager or .env file with .gitignore).

Rotate API keys periodically. Both Linear and Jira allow you to revoke and regenerate API keys. Do this every 90 days as a security best practice.

Use scoped permissions. Where possible, generate API keys with only the permissions the agent needs (read-only access to issues, sprints, and team data — not write access).