Headless Project Management (Headless JIRA)

AI workflow automation from Teams and PRs to Jira.

Headless Project Management is an open-source automation layer that converts meeting communication into Jira artifacts and keeps Jira updated with actual delivery data from pull requests.

Status

• Current stage: Alpha
• Primary focus: end-to-end automation reliability for Teams -> Jira and PR -> Jira enrichment
• Python baseline: 3.11+

Vision

1. Reduce manual effort of translating meeting notes into Jira artifacts.
2. Extract epics, stories, tasks, and bugs from Microsoft Teams transcripts using AI.
3. Amend Jira issues from GitHub pull request activity so issues reflect delivered work.

Why This Matters

• For developers: spend less time rewriting meeting and PR context into Jira, and more time building.
• For managers: turn conversations into trackable execution faster, with more reliable status visibility.
• For teams: create a clear chain from discussion -> implementation -> delivery without manual follow-up.

Current Status

This repository currently contains the Phase 1 foundation:

• Monorepo-oriented project structure with apps/ and packages/
• FastAPI service scaffold
• Transcript normalization logic
• Structured extraction contract and pipeline
• Jira client abstraction
• Initial tests and quality tooling configuration

Repository Layout

apps/
  api/
packages/
  domain/
  extraction/
  ingestion/
  integrations/
tests/
docs/

Community

• Contributing guide: CONTRIBUTING.md
• Code of conduct: CODE_OF_CONDUCT.md
• Security policy: SECURITY.md
• Support guide: SUPPORT.md

For release hygiene and publication checks, see docs/open-source-release-checklist.md.

Quick Start

1. Create and activate a virtual environment.
2. Install dependencies:

pip install -e .[dev]

3. Run tests:

pytest

4. Start API:

uvicorn apps.api.main:app --reload

5. Configure AI extraction (optional but recommended):

• Set OPENAI_API_KEY in .env.
• Optionally override OPENAI_MODEL and EXTRACTION_CONFIDENCE_THRESHOLD.

When the API key is configured, extraction uses OpenAI with strict JSON-schema output validation. If provider calls fail, the service falls back to a local heuristic extractor and marks low-confidence items for human review.

5.1 Configure Microsoft Teams polling integration (Phase 2):

• Set MS_TENANT_ID, MS_CLIENT_ID, and MS_CLIENT_SECRET.
• Grant Microsoft Graph app permissions required to read Teams channel messages.

Teams polling endpoint:

• POST /transcripts/teams/poll with team_id, channel_id, and optional max_results.
• The API normalizes each returned message and includes a deterministic source_hash for downstream idempotency.

Teams meeting transcript endpoint:

• POST /transcripts/teams/meeting-transcript with user_id, meeting_id, and optional transcript_id.
• Fetches transcript artifacts from Microsoft Graph online meeting transcript endpoints.
• Uses v1.0 first, then falls back to beta for tenants where transcript APIs are not available on v1.0.
• Normalizes transcript content and returns a deterministic source_hash.

One-call meeting transcript publish endpoint:

• POST /transcripts/teams/meeting-transcript/publish with user_id, meeting_id, and optional transcript_id.
• Executes transcript fetch -> extraction -> Jira publish in a single request.
• Returns transcript record, extraction payload, and created/reused Jira keys.

6. Configure Jira publish integration:

• Set JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN, and JIRA_PROJECT_KEY.
• Optionally override issue type names with JIRA_ISSUE_TYPE_EPIC, JIRA_ISSUE_TYPE_STORY, JIRA_ISSUE_TYPE_TASK, and JIRA_ISSUE_TYPE_BUG.

Jira publish uses authenticated Jira Cloud REST API calls and applies idempotency using source-hash labels (hpm-source-<full-hash>). Replays of the same transcript artifact try to reuse existing issues instead of creating duplicates.

Phase 1.2 behavior details:

• Auth: Jira Cloud API token auth via JIRA_EMAIL + JIRA_API_TOKEN.
• Issue type mapping: configurable with JIRA_ISSUE_TYPE_EPIC/STORY/TASK/BUG.
• Idempotency: each issue is tagged with a deterministic source label and item label derived from source hash + artifact type + title.

MVP Flow (Phase 1)

1. Submit a transcript payload to /transcripts/submit.
2. Preview extracted items through /transcripts/extract.
3. Publish selected extraction to Jira through /jira/publish.

Teams Polling Flow (Phase 2)

1. Poll Teams channel messages through /transcripts/teams/poll.
2. Receive normalized records with source hashes.
3. Feed selected records to extraction and Jira publish flows.

Teams Meeting Transcript Flow

1. Call /transcripts/teams/meeting-transcript with organizer user_id and meeting_id.
2. Receive normalized transcript record with source hash.
3. Feed transcript text into extraction and Jira publish flows.

Autonomous Discovery Flow (No Meeting Arguments)

1. Configure MS_DISCOVERY_USER_IDS with comma-separated organizer/user IDs.
2. Trigger POST /transcripts/teams/discovery/run to discover recent meetings and queue candidates.
3. Trigger POST /transcripts/teams/discovery/process-next repeatedly (or from a worker loop) to process queued meetings end-to-end.
4. Each processing step fetches transcript, extracts Jira artifacts, and publishes to Jira without manual meeting_id input.

Discovery state is persisted in SQLite using MEETING_DISCOVERY_DB_PATH, with retry/backoff controls via MEETING_DISCOVERY_MAX_RETRIES and MEETING_DISCOVERY_BACKOFF_MINUTES.

GitHub PR Webhook Flow (Phase 3a)

1. Configure GITHUB_WEBHOOK_SECRET and set webhook URL to /github/webhooks/pull-request.
2. Configure GITHUB_DRY_RUN_MODE=true to test without Jira mutations.
3. Webhook signature is validated using X-Hub-Signature-256 before processing.
4. PR payload is parsed, Jira keys are extracted from title/body, and comment-only enrichment is applied.
5. Delivery IDs are tracked in a SQLite idempotency store to avoid duplicate amendments.

End-to-End Publish Run

After setting required variables in a local .env, run:

python scripts/run_e2e_publish.py

The script runs transcript submission, extraction, and Jira publish in one flow and prints created or reused Jira keys.

Phase 1.3 demo details:

• Uses transcript fixtures under fixtures/transcripts/.
• Uses Jira sandbox project by default via JIRA_SANDBOX_PROJECT_KEY when set.
• Falls back to JIRA_PROJECT_KEY when sandbox key is not provided.

Examples:

python scripts/run_e2e_publish.py
python scripts/run_e2e_publish.py --fixture fixtures/transcripts/bug_triage_001.txt
python scripts/run_e2e_publish.py --meeting-id demo-meeting-042 --project-key HPM-SBX

License

Apache-2.0