Getting Started

spectryn is a production-grade CLI tool for synchronizing markdown documentation with issue trackers. Write your epic docs in markdown, sync to your favorite tracker automatically.

Supported Trackers

spectryn supports 14 issue trackers out of the box:

Tracker	Type	Best For
Jira	Enterprise	Large teams, complex workflows
GitHub Issues	Developer	Open source, code-centric teams
GitLab Issues	DevOps	GitLab-native projects
Azure DevOps	Enterprise	Microsoft ecosystem
Linear	Startup	Fast-paced product teams
Asana	Collaboration	Cross-functional teams
Trello	Visual	Kanban workflows
ClickUp	All-in-one	Feature-rich needs
Shortcut	Agile	Engineering teams
Monday.com	Work OS	Marketing & operations
Plane	Open source	Self-hosted preference
YouTrack	JetBrains	IntelliJ users
Basecamp	Simple	Small teams
Bitbucket	Atlassian	Bitbucket repos
Pivotal Tracker	Agile	Story-based planning

Why spectryn?

Managing issues through web interfaces is slow and tedious. Developers prefer working with markdown files that can be:

• ✅ Version controlled with Git
• ✅ Reviewed in pull requests
• ✅ Edited with your favorite editor
• ✅ Generated with AI assistants

spectryn bridges the gap between markdown-first documentation and project management.

Key Features

Feature	Description
Multi-Tracker Support	14 trackers with unified markdown format
Full Epic Sync	Sync stories, subtasks, descriptions, comments
Smart Matching	Fuzzy matching between markdown and tracker issues
Safe by Default	Dry-run mode, confirmations, previews
Backup & Rollback	Automatic backups before sync, easy rollback
Plugin System	Extensible architecture for custom adapters

How It Works

graph LR
    A[📝 Markdown File] --> B[spectryn CLI]
    B --> C{Dry Run?}
    C -->|Yes| D[📊 Preview Changes]
    C -->|No| E[☁️ Tracker API]
    E --> F[✅ Issues Updated]

1. Write your epic documentation in markdown following the schema
2. Preview changes with dry-run mode (default)
3. Sync to your tracker with --execute flag
4. Verify results in your tracker or with audit trail

Quick Example

Create a markdown file with your epic:

### 🚀 STORY-001: User Authentication

| Field | Value |
|-------|-------|
| **Story Points** | 5 |
| **Priority** | 🟡 High |
| **Status** | 📋 Planned |

#### Description

**As a** user
**I want** to authenticate securely
**So that** my data is protected

#### Subtasks

| # | Subtask | Description | SP | Status |
|---|---------|-------------|:--:|--------|
| 1 | Create login form | Build the login UI | 2 | 📋 Planned |
| 2 | Implement JWT auth | Add JWT token handling | 3 | 📋 Planned |

Sync to your tracker:

Jira

spectryn sync --tracker jira --markdown EPIC.md --epic PROJ-123 --execute

GitHub

spectryn sync --tracker github --markdown EPIC.md --repo owner/repo --execute

GitLab

spectryn sync --tracker gitlab --markdown EPIC.md --project mygroup/myproject --execute

Linear

spectryn sync --tracker linear --markdown EPIC.md --team TEAM --execute

Azure DevOps

spectryn sync --tracker azure --markdown EPIC.md --project MyProject --execute

Next Steps

📦 Installation
Install via pip, Homebrew, or Docker⚡ Quick Start
Your first sync in 5 minutes📐 Schema Reference
Complete markdown format guide🤖 AI Fix
Fix formatting issues with AI assistance