Integration

Integration Rules

Linear Integration

See the linear skill for full Linear rules and CLI commands (skills/linear/).

Quick reference:

• CLI Tool: Linearis (linearis command)
• Default Team: Self Driven Platform (PLTFRM)
• Default Status: Backlog
• Issue URLs: Always use full markdown format

GitHub Integration

GitHub CLI Usage

• MANDATORY: Always use GitHub CLI (gh) for viewing GitHub logs and repository information
• Use gh commands instead of web interface for log access and repository operations
• Prefer gh CLI over browser-based GitHub operations when possible

Core Commands

• gh log - View commit logs and repository history
• gh pr view - Pull request information
• gh issue view - Issue details
• gh repo view - Repository information

GitHub Actions

• gh run list - View workflow runs
• gh run view <run-id> - View specific workflow run details
• gh run logs <run-id> - View workflow logs
• gh workflow list - List available workflows
• gh workflow view <workflow-name> - View workflow details
• gh run watch <run-id> - Watch a workflow run in real-time
• gh run rerun <run-id> - Rerun failed workflows

Pull Request Management

• Use .github/pull_request_template.md
• Define code ownership rules in .github/CODEOWNERS
• Use consistent labeling system (feat, fix, chore, docs)
• Require appropriate number of reviewers
• Assign reviewers based on code ownership

Trunk Integration

Fix workflow (agent)

When fixing lint/format issues in a Trunk-enabled project: run trunk check --fix first so Trunk auto-fixes what it can; then fix manually whatever remains. Do not skip Trunk—use it first, then the agent.

Tool Configuration

• Prefer configuring tools and linters using their standard configuration files in default paths (e.g., .eslintrc, pyproject.toml, .prettierrc) instead of configuring exclusively in .trunk/
• Keep .trunk/trunk.yaml minimal - use it only for Trunk-specific settings like enabled linters and actions
• This ensures tools work consistently whether run via Trunk or directly

Ignore Configuration

• Prefer using each tool's native ignore mechanism (inline comments or ignore files) instead of Trunk's ignore system
• Examples:
  • ESLint: // eslint-disable-next-line or .eslintignore
  • Prettier: // prettier-ignore or .prettierignore
  • Ruff: # noqa or pyproject.toml exclude patterns
• This maintains compatibility when tools are run outside of Trunk

MCP (Model Context Protocol) Integration

Server Configuration

• Configure MCP servers in mcp.json
• Test server connections regularly
• Monitor server performance
• Document server purposes and usage

Tool Integration

• Linear: Use Linearis CLI as primary tool; MCP only as fallback for unsupported operations
• Use GitHub MCP tools for repository operations
• Leverage web search capabilities
• Monitor tool usage and performance

External Service Integration

API Integration

• Use consistent error handling
• Implement proper retry logic
• Monitor API rate limits
• Handle service failures gracefully
• Log integration issues

Authentication

• Use secure authentication methods
• Store credentials securely
• Implement token refresh logic
• Monitor authentication status
• Handle authentication failures

Data Synchronization

• Ensure data consistency across services
• Handle sync conflicts appropriately
• Monitor sync status
• Implement conflict resolution
• Regular sync validation

Workspace Integration

Multi-Repository Support

• Handle multiple git repositories
• Identify repository boundaries
• Manage cross-repository dependencies
• Provide clear repository context
• Support repository-specific configurations

Environment Management

• Support different environments (dev, staging, prod)
• Use environment-specific configurations
• Handle environment-specific secrets
• Validate environment requirements
• Monitor environment health

Monitoring and Observability

Integration Monitoring

• Monitor integration health
• Track integration performance
• Set up alerts for integration failures
• Log integration events
• Regular integration testing

Error Handling

• Implement comprehensive error handling
• Provide clear error messages
• Log integration errors
• Implement error recovery
• Monitor error patterns

Performance Monitoring

• Track integration response times
• Monitor resource usage
• Identify performance bottlenecks
• Optimize slow integrations
• Regular performance reviews

Security Integration

Secure Communication

• Use HTTPS for all external communications
• Implement proper certificate validation
• Use secure authentication protocols
• Monitor for security vulnerabilities
• Regular security audits

Data Protection

• Encrypt sensitive data in transit
• Use secure storage for credentials
• Implement access controls
• Monitor data access patterns
• Regular security reviews

Documentation and Maintenance

Integration Documentation

• Document all integrations
• Provide setup instructions
• Include troubleshooting guides
• Update documentation regularly
• Maintain integration examples

Regular Maintenance

• Review integration configurations
• Update integration versions
• Test integration functionality
• Monitor integration performance
• Plan integration improvements