Integrations

Plug-ins that close operational cycles

Integrations connect the harness to external systems. They close SDLC loops — without a work_items integration, tickets cannot flow; without deploy, releases cannot complete; without observability, incidents cannot trigger remediation.

They are not the product. The product is the harness (DSL + materialization + gates). Integrations are plug-ins whose manifests are generated at init by commands, skills, and the integration mutator — not shipped pre-filled.

---

Lifecycle slots

The DSL defines canonical slots. Each slot maps to one phase of the SDLC flow:

Slot	Phase	Example providers
work_items	Ticket/epic management	Plane, Jira, Linear, Notion, GitHub Issues
source_control	Repository, PRs, branch policy	GitHub, GitLab, Bitbucket
ci	Build, lint, test gates	GitHub Actions, GitLab CI, CircleCI
qa	E2E / evidence capture	Playwright, Cypress (stack declaration, often no manifest)
observability	Errors, analytics, replay	PostHog, Sentry, Datadog
deploy	Staging/production release	Cloudflare Pages, Railway, Fly.io, AWS
post_deploy	Smoke, rollback gate	Same as deploy + browser automation
incident	Autonomous remediation	GitHub Issues + agent SDK, PagerDuty webhook

During init, the runtime walks slots conversationally. User may supply intent in one utterance:

/sdlc:init python-fastapi + postgres + Jira + GitHub Actions + Railway + Sentry

The agent maps tokens to slots + stack profile, confirms, then materializes manifests.

---

How manifests are generated

The npm package ships an integration catalog — read-only templates at templates/integrations/{provider}/ with JSON Schema, secrets_required metadata, and API examples. This catalog is reference material, not copied wholesale to the project.

Materialization pipeline (shared by init and config):

Slot selection
    ↓
/sdlc:init or /sdlc:config directive
    ↓
.sdlc/pipeline/integration-mutator.ts
    ↓
.sdlc/integrations/{provider}/{provider}.yaml   ← generated
    ↓
sdlc.yaml integrations: index updated
    ↓
Doctor validates serves_slots + credentials

Each materialized provider declares which slots it covers:

integrations:
  jira:
    config: .sdlc/integrations/jira/jira.yaml
    status: active
    serves_slots: [work_items]
  github:
    config: .sdlc/integrations/github/github.yaml
    status: active
    serves_slots: [source_control, ci]

Non-selected providers do not exist as directories. Doctor validates: required slots covered, no duplicate slot assignment, credentials present for active integrations.

---

Work-items provider is swappable

The SDLC flow requires a ticket before implementation (constraints.plane_ticket_required in the DSL — the constraint name is historical; it means work-items ticket required).

Tickets can live anywhere:

Provider	Typical use
Plane	Full project management with evidence attachments
Jira	Enterprise sprint tracking
Linear	Startup issue tracking
Notion	Database-backed work items
GitHub Issues	Minimal, repo-scoped tickets

The workflow is identical:

1. /spec:create reads ticket from active provider via skill
2. Feature work proceeds in worktree
3. PR creation links ticket
4. Post-merge: ticket → Done, evidence uploaded per provider API

Skills (plane-ticket, or provider-specific variants generated at init) encapsulate API calls. Workflow YAML names operations, not vendors.

Swap provider post-init:

/sdlc:config swap work_items from plane to jira

Mutator removes old manifest, generates new one, updates DSL index. Doctor re-validates.

---

Integration manifest contents

Each generated manifest owns:

provider: jira
slot: work_items
secrets_required:
  - name: JIRA_API_TOKEN
    scope: [local, ci]
    description: Personal API token for Jira Cloud
api:
  base_url: https://{org}.atlassian.net
  endpoints:
    get_issue: /rest/api/3/issue/{key}
    transition: /rest/api/3/issue/{key}/transitions
bindings:
  project_key: PROJ
  default_issue_type: Story

Doctor Check Group 4 reads secrets_required from all active integration manifests and validates credential presence in local .env and CI secrets.

---

MCPs are separate from integrations

MCP servers and integrations serve different layers:

Layer	What it is	Configuration
Integration	SDLC lifecycle slot binding	Generated manifest in .sdlc/integrations/
MCP	Runtime tool server for agent actions	User-level (e.g., ~/.cursor/mcp.json)

An integration manifest tells the SDLC which API to call for ticket sync. An MCP gives the agent how to call it during execution (browser automation, GitHub API, etc.).

Both are user/setup dependent. Neither ships pre-configured in the core package.

---

Authoring repository vs consumer project

The authoring repo (this repository) has active integrations for dogfooding — Plane, GitHub, Cloudflare Pages. These are this project’s choices, not defaults every consumer receives.

Consumer project after init:

their-repo/
├── .sdlc/
│   ├── sdlc.yaml              # their slot selections
│   └── integrations/          # only their chosen providers
│       └── jira/jira.yaml
├── .cursor/                   # or .claude/, etc.
└── {target_root}/             # their application — unchanged by install

---

Operational consequences

Empty integrations is valid. Install + init with only work_items: github-issues and source_control: github produces two manifests. Nothing else.

Manifests are generated, not edited by hand. Direct YAML edits drift from DSL index. Use /sdlc:config or init slot walk.

Doctor is the integration gate. Operational status requires credential validation against active manifests — not against a fixed vendor list.

Flow is provider-agnostic. Changing Jira → Linear changes one manifest and one skill binding. Workflows and gates are unchanged.