Plan: Configurable default labels for issue tracker integrations

[NoahCardoza]

Problem statement

Teams adopting iloom-cli have no reliable, org-wide way to distinguish AI-assisted tickets from human-authored ones in their issue tracker. Agents can technically supply labels via the MCP create_issue tool, but relying on agent behavior is non-deterministic — labels get missed, inconsistent, or dropped silently (Jira drops them entirely today).

A settings-driven default would make every iloom-created ticket identifiable without relying on agent instructions.

Goals

• Configure a list of labels in settings.json that get applied automatically to every issue created through iloom-cli
• Merge configured defaults with any agent-supplied labels (union, dedup) so configured identifiers are always present
• Propagate the config through the MCP env-var bridge so the issue-management MCP server picks it up
• Deliver for GitHub and Jira in this epic

Scope

In scope:

• GitHub and Jira tracker providers
• New settings.issueManagement.{github,jira}.defaultLabels: string[] config (defaults to [])
• Configured defaults merged (case-sensitive union with dedup, configured-first order) with agent-supplied labels
• MCP env-var bridge propagates config to the subprocess
• Documentation in docs/iloom-commands.md

Out of scope:

• Linear: Labels are currently unimplemented in iloom-cli's Linear integration (createLinearIssue and createLinearChildIssue in src/utils/linear.ts silently drop the _labels parameter), and Linear's SDK requires resolving label names to label UUIDs via a lookup helper that does not yet exist. Deferred to a follow-up epic focused on Linear label support.
• Legacy JiraIssueTracker.createIssue CLI path (unused by the MCP-driven issue creation flow)
• First-run-setup prompting
• Telemetry (no workflow change)

Summary of approach

One config-surface change (schema + env bridge + docs) establishes the contract. Two parallel per-tracker wiring changes (GitHub and Jira) consume the contract and merge the configured defaults with agent-supplied labels before the label list reaches each tracker's API. A final integration verification confirms the wires are connected end-to-end.

Task overview

#	Title	Description	Dependencies	Complexity
1	Add defaultLabels to settings schema + env-var bridge + docs	Extend settings schema and MCP env-var bridge with defaultLabels for GitHub and Jira; document in settings reference.	None	Simple
2	Apply defaultLabels in Jira provider + API client	Merge configured + agent labels in Jira MCP provider; forward as fields.labels in REST API POST body.	Task 1	Simple
3	Apply defaultLabels in GitHub provider	Merge configured + agent labels in GitHub MCP provider; forward to existing gh CLI label pipeline.	Task 1	Simple
4	Verify default-label integration	Integration tests confirming merged-label flow end-to-end for both providers with no regression when unset.	Tasks 2, 3	Simple

Detailed breakdown

The full implementation breakdown — per-task acceptance criteria, shared contracts, scope boundaries, must-haves, and the architectural decision record — is posted as a comment on this issue.

Note

An earlier version of this plan was incorrectly created as four separate issues (#986, #987, #988, #989). Those have been closed; this issue is the single source of truth for the plan.

[NoahCardoza]

Detailed task breakdown

Task 1 — Add defaultLabels to settings schema + env-var bridge + docs

Summary: Extend the iloom settings schema with a defaultLabels: string[] field under issueManagement.github and issueManagement.jira, propagate it through the MCP env-var bridge, and document it.

Acceptance criteria:

• A settings.json containing issueManagement.github.defaultLabels: ["iloom"] and issueManagement.jira.defaultLabels: ["iloom", "ai-generated"] loads successfully and the values are accessible on the parsed settings object.
• A settings.json containing an empty string in defaultLabels fails settings validation with a clear error message identifying the invalid entry.
• Omitting defaultLabels is backwards compatible — the effective value is an empty array; existing settings files continue to load without warnings or errors.
• When the MCP issue-management server is spawned as a subprocess, the configured labels are available as environment variables GITHUB_DEFAULT_LABELS and JIRA_DEFAULT_LABELS (JSON-stringified arrays).
• The settings reference in docs/iloom-commands.md includes a defaultLabels row under both the GitHub and Jira tracker configuration tables, with description and example value.

Shared contracts (produces):

• settings.issueManagement.github.defaultLabels: string[] (optional, defaults to [])
• settings.issueManagement.jira.defaultLabels: string[] (optional, defaults to [])
• Environment variables GITHUB_DEFAULT_LABELS and JIRA_DEFAULT_LABELS (JSON-stringified arrays; absent when list is empty)
• Labels validated as non-empty strings at the schema layer; tracker-specific format rules enforced by providers at runtime

Dependencies: None

Scope boundaries:

• Does NOT modify any tracker provider or MCP tool handler
• Does NOT modify Linear configuration
• Does NOT change first-run-setup prompts

Must-haves:

• substantive: src/lib/SettingsManager.ts — both IloomSettingsSchema and IloomSettingsSchemaNoDefaults declare defaultLabels under issueManagement.github and issueManagement.jira
• substantive: src/utils/mcp.ts — generateIssueManagementMcpConfig serializes GitHub and Jira defaultLabels to GITHUB_DEFAULT_LABELS / JIRA_DEFAULT_LABELS env vars as JSON
• substantive: docs/iloom-commands.md — GitHub and Jira settings reference tables include a defaultLabels row with description and example

Complexity: Simple

---

Task 2 — Apply configured defaultLabels in Jira provider and API client

Summary: Wire defaultLabels through the Jira MCP provider so configured labels are merged with agent-supplied labels and attached to newly created Jira issues and sub-tasks.

Acceptance criteria:

• A Jira issue created via the MCP create_issue tool, with defaultLabels: ["iloom"] configured, shows iloom in its Labels field when viewed in Jira.
• A Jira sub-task created via create_child_issue with the same config also shows iloom in its Labels field.
• When an agent passes labels: ["ai-generated"] AND defaultLabels: ["iloom"] is configured, the created Jira issue has exactly iloom and ai-generated in its Labels field (order: configured first, deduplicated).
• If a configured or agent-supplied label contains whitespace (which Jira rejects), issue creation fails with a clear error that names the offending label — not a raw Jira 400.
• When no defaultLabels are configured and no agent labels are passed, issue creation produces the same outcome as before this change.

Shared contracts (consumes):

• settings.issueManagement.jira.defaultLabels: string[] and the JIRA_DEFAULT_LABELS env var (from Task 1)
• Merge rule: case-sensitive union with dedup, configured labels first

Shared contracts (produces):

• JiraApiClient.createIssue and JiraApiClient.createIssueWithParent include labels in fields.labels of the Jira REST POST body when labels are provided

Dependencies: Task 1

Scope boundaries:

• Does NOT modify the legacy JiraIssueTracker.createIssue CLI path
• Does NOT change agent-facing MCP tool schemas
• Does NOT add Linear support

Must-haves:

• substantive: src/lib/providers/jira/JiraApiClient.ts — createIssue and createIssueWithParent include fields.labels in the POST body when labels are provided
• substantive: src/mcp/JiraIssueManagementProvider.ts — createIssue and createChildIssue merge configured defaultLabels with input labels (dedup, configured-first) and forward to the API client
• wired: src/mcp/JiraIssueManagementProvider.ts — getJiraTrackerConfig reads defaultLabels from settings and the JIRA_DEFAULT_LABELS env var fallback

Complexity: Simple

---

Task 3 — Apply configured defaultLabels in GitHub provider

Summary: Merge configured defaultLabels with agent-supplied labels in the GitHub MCP provider so every GitHub issue created by iloom carries the configured defaults.

Acceptance criteria:

• A GitHub issue created via the MCP create_issue tool, with defaultLabels: ["iloom"] configured, has the iloom label applied in the target repository.
• A GitHub sub-issue created via create_child_issue with the same config has the iloom label applied.
• When an agent passes labels: ["bug"] AND defaultLabels: ["iloom"] is configured, the created issue has exactly iloom and bug (order: configured first, deduplicated), with no duplicate --label arguments passed to gh.
• When no defaultLabels are configured and no agent labels are passed, issue creation produces the same outcome as before this change.

Shared contracts (consumes):

• settings.issueManagement.github.defaultLabels: string[] and the GITHUB_DEFAULT_LABELS env var (from Task 1)
• Merge rule: case-sensitive union with dedup, configured labels first

Dependencies: Task 1

Scope boundaries:

• Does NOT modify the gh CLI invocation itself (labels are already supported there)
• Does NOT auto-create missing labels on the target repository (remains user responsibility, as today)
• Does NOT add Linear support

Must-haves:

• substantive: src/mcp/GitHubIssueManagementProvider.ts — createIssue and createChildIssue merge configured defaultLabels (read from settings / GITHUB_DEFAULT_LABELS env var) with agent-supplied labels using dedup and configured-first order before forwarding to the existing utility

Complexity: Simple

---

Task 4 — Verify default-label integration across GitHub and Jira providers

Summary: Integration verification confirming that configured defaultLabels flow end-to-end through both providers, combine correctly with agent-supplied labels, and preserve existing behavior when unset.

Acceptance criteria:

• pnpm build against the merged branch completes without TypeScript errors.
• pnpm test against the merged branch passes (existing and any new tests).
• With settings.json configured with non-empty defaultLabels for both GitHub and Jira, issue and child-issue creation via the MCP tools attaches the merged (configured + agent-supplied) label set in the final request sent to each tracker.
• With defaultLabels omitted or empty for either tracker, issue creation produces the same outcome as before the epic (no labels attached when no agent labels are supplied).

Shared contracts: None produced; consumes contracts from Tasks 1, 2, 3.

Dependencies: Tasks 2, 3

Scope boundaries:

• Does NOT modify production source code; test/integration-verification only
• Does NOT cover Linear or the legacy JiraIssueTracker.createIssue CLI path

Must-haves:

• substantive: tests covering both providers — verify that when configured defaultLabels is non-empty and agent labels are also provided, the final label set forwarded to the tracker is the deduped union in configured-first order
• substantive: tests covering both providers — verify that when defaultLabels is empty/unset and no agent labels are passed, no labels are attached to created issues

Complexity: Simple

---

Dependency diagram

graph TD
    T1[Task 1 - Settings schema + env bridge + docs]
    T2[Task 2 - Jira provider + API client]
    T3[Task 3 - GitHub provider]
    T4[Task 4 - Integration verification]
    T1 --> T2
    T1 --> T3
    T2 --> T4
    T3 --> T4

Loading

Architectural Decision Record

Key decisions

Decision	Choice	Rationale
Config surface	New defaultLabels: string[] under issueManagement.{github,jira}	Mirrors the existing per-tracker config pattern (defaultIssueType, doneStatuses, etc.) — keeps the schema shape consistent
Merge behavior	Case-sensitive union with dedup, configured labels first	Ensures every iloom-created ticket carries the configured identifier labels while preserving legitimate agent-supplied labels (e.g., bug on GitHub)
Schema validation	Non-empty strings at the schema; tracker-specific format rules at runtime	GitHub and Linear allow spaces in labels; Jira rejects them. A globally strict schema would break GitHub use cases
Linear exclusion	Deferred to a follow-up epic	See "Linear exclusion" section below
Legacy CLI path	Not modified (JiraIssueTracker.createIssue in src/lib/providers/jira/JiraIssueTracker.ts)	Unused by the MCP-driven issue creation flow
Telemetry	Not included	Config feature, not a user workflow change
First-run-setup prompt	Not included	Documented example in docs/iloom-commands.md is sufficient

Linear exclusion

Linear was initially scoped in and then removed after deeper codebase inspection:

• Labels are completely unimplemented today in iloom-cli's Linear integration: createLinearIssue and createLinearChildIssue in src/utils/linear.ts accept a _labels?: string[] parameter (underscore-prefixed, unused) and silently drop it.
• Linear's SDK requires label IDs, not names: issueCreate accepts labelIds: string[] (UUIDs). No name → ID resolution helper exists today anywhere in the codebase.
• Adding Linear would require building a net-new label resolver (Linear SDK team.labels() query), plus deciding the behavior for unknown names, case sensitivity, and team-vs-workspace label scope — all net-new design surface beyond a simple settings pass-through.

Deferred to a follow-up epic scoped specifically to Linear label support. That epic will establish the resolver once, and the defaultLabels wiring for Linear will be a thin addition on top.

Design notes

• Validation happens at two layers: Schema layer (non-empty strings) catches obvious errors early; tracker providers enforce tracker-specific rules at runtime with errors that name the offending label (not raw API 400s).
• Env-var bridge serializes as JSON: Follows the existing JIRA_TRANSITION_MAPPINGS pattern — arrays and objects are JSON-stringified for subprocess transport.

Suggested execution order

1. Wave 1: Task 1 (settings schema + env bridge + docs) — must merge first
2. Wave 2 (parallel): Task 2 (Jira) and Task 3 (GitHub) — both blocked on Task 1; can run simultaneously
3. Final verification: Task 4 — blocks on both Task 2 and Task 3

A maintainer with write access can create the child issues and dependencies from this breakdown.

[NoahCardoza]

@acreeger What do you think of this feature? Since labels aren't currently supported on linear, I decided not to support them for this.

I didn't realize #729 wasn't merged. I didn't tell claude to keep it all in one issue.

[acreeger]

I like this! Totally missed it so didn't even realize. I can have it planned/implemented.

Thanks!!

[NoahCardoza]

Complexity Analysis

Per-task sizing

Task	Files	LOC (est)	Risk	Classification	Complexity signals
1. Settings schema + env bridge + docs	3 production + tests (SettingsManager.ts, mcp.ts, docs/iloom-commands.md)	~60–80	Low	SIMPLE	Additive; no runtime behavior change. Must update the dual schema (IloomSettingsSchema + IloomSettingsSchemaNoDefaults) — a known footgun but well-established pattern.
2. Jira provider + API client	3 production + tests (JiraApiClient.ts, JiraIssueTracker.ts, JiraIssueManagementProvider.ts)	~100–140	Low–Medium	SIMPLE	Net-new fields.labels forwarding in API client; merge + runtime validation in provider. Removes an explicit "not supported" comment.
3. GitHub provider	1 production + tests (GitHubIssueManagementProvider.ts)	~30–50	Low	SIMPLE (borderline TRIVIAL)	Label forwarding to gh already works; this just adds a provider-layer merge step.
4. Integration verification	Test files only	~80–120	Low	SIMPLE	Behavior tests covering merge semantics per provider; no production code.

Overall epic

Dimension	Estimate
Total new/modified production files	5–6
Total LOC (including tests)	~300–400
PRs expected	4 (one per task)
Parallelism	Tasks 2 and 3 fully parallel after Task 1
Backwards-compatibility risk	None — additive field defaulting to []
Duration estimate	1–2 focused working days

Complexity drivers and watch-outs

• Dual-schema drift: IloomSettingsSchema vs IloomSettingsSchemaNoDefaults both require the new field. Prior additions (e.g. doneStatuses) maintain this pattern; missing it silently breaks partial-settings validation.
• Dual config-read path in Jira provider: getJiraTrackerConfig reads from both settings and the JIRA_* env-var fallback. Both paths must surface defaultLabels or behavior diverges between in-process and subprocess invocation.
• Merge semantics invariant across tasks: Tasks 2, 3, and 4 must apply identical merge rules — case-sensitive union, configured-first, deduplicated. A shared mergeLabels helper is a natural abstraction but optional given the small number of call sites.
• Validation split between layers: Schema layer rejects empty strings only; Jira's no-whitespace rule lives in the provider so GitHub/Linear's spaces-allowed labels remain valid.
• Stale "not supported" comment: JiraIssueManagementProvider.createIssue has a comment stating "labels not supported in current implementation". Task 2 must remove it — leaving it behind would mislead future readers.
• GitHub label preexistence: gh issue create --label <name> errors if the label doesn't exist on the repo. Users configuring defaultLabels must pre-create matching labels. Worth calling out in the docs row.

Why everything stays SIMPLE

No task requires: architectural decisions, database migrations, breaking-change coordination, or cross-cutting parameter threading through >3 layers. Each task touches a tightly-scoped surface with clear inputs and outputs, and Tasks 2/3 consume a stable contract from Task 1. The work is wiring, not design.

[NoahCardoza]

Planning & Implementation Across All Tasks

Overall strategy

Wave-based execution: Task 1 establishes the configuration contract; Tasks 2 and 3 consume it in parallel; Task 4 verifies end-to-end wiring after both wiring tasks merge. Each task is a single PR.

   Task 1 (settings/env/docs)
         │
    ┌────┴────┐
    ▼         ▼
  Task 2    Task 3
  (Jira)    (GitHub)
    │         │
    └────┬────┘
         ▼
      Task 4 (verify)

---

Task 1 — Settings schema + env-var bridge + docs

Files to modify:

• src/lib/SettingsManager.ts — both IloomSettingsSchema and IloomSettingsSchemaNoDefaults
• src/utils/mcp.ts — generateIssueManagementMcpConfig
• docs/iloom-commands.md — settings reference tables for GitHub and Jira
• src/lib/SettingsManager.test.ts — schema validation tests

Implementation outline:

1. In IloomSettingsSchema.issueManagement.github, add defaultLabels: z.array(z.string().min(1)).default([]). Mirror in issueManagement.jira. Do the same in the IloomSettingsSchemaNoDefaults duplicates.
2. In generateIssueManagementMcpConfig, extend the GitHub branch to set GITHUB_DEFAULT_LABELS = JSON.stringify(github.defaultLabels) when non-empty. Mirror for Jira (JIRA_DEFAULT_LABELS).
3. In the docs settings reference, add a defaultLabels row under each tracker's table describing the merge behavior and including an example value.

Test strategy:

• Schema accepts valid defaultLabels arrays.
• Schema rejects empty strings in the array with a clear error.
• Omitting the field defaults to [].
• Env-var serialization produces correct JSON when labels configured, and no env var when the list is empty.

Ship criteria: Task 1 can release independently — it's a pure configuration surface with no runtime behavior change.

---

Task 2 — Jira provider + API client

Files to modify:

• src/lib/providers/jira/JiraApiClient.ts
• src/lib/providers/jira/JiraIssueTracker.ts
• src/mcp/JiraIssueManagementProvider.ts
• Associated test files

Implementation outline:

1. Add a labels parameter to JiraApiClient.createIssue and createIssueWithParent; include labels as fields.labels in the POST body when provided. A short options-bag refactor of the positional signature is worth considering if it keeps test call-sites readable.
2. Extend JiraTrackerConfig in JiraIssueTracker.ts with defaultLabels?: string[], and update JiraIssueTracker.createIssue to accept and forward labels to the API client (replace the unused _labels placeholder).
3. In JiraIssueManagementProvider.getJiraTrackerConfig, read defaultLabels from both settings.issueManagement.jira.defaultLabels and the JIRA_DEFAULT_LABELS env-var fallback (JSON-parsed). Both paths must set the same config field.
4. In JiraIssueManagementProvider.createIssue and createChildIssue:
   • Remove the "labels not supported in current implementation" comment.
   • Merge this.tracker.getConfig().defaultLabels with input.labels — case-sensitive union, configured-first, deduplicated.
   • Validate each label (reject whitespace with an error that names the offending label).
   • Forward the merged list to the tracker/API client.

Test strategy:

• Merge order: ["iloom"] configured + ["ai-generated"] input → ["iloom", "ai-generated"] in fields.labels.
• Deduplication: overlapping labels appear once, first occurrence wins.
• Whitespace label triggers a clear error naming the offending value.
• No labels attached when neither configured nor supplied (regression check).
• fields.labels appears in POST body only when labels are non-empty.

---

Task 3 — GitHub provider

Files to modify:

• src/mcp/GitHubIssueManagementProvider.ts
• Associated test file

Implementation outline:

1. In the provider's constructor or per-call setup, read defaultLabels from settings (with GITHUB_DEFAULT_LABELS env var as the fallback path).
2. In createIssue and createChildIssue, merge configured defaultLabels with the input.labels array — case-sensitive union, configured-first, deduplicated — before passing labels along to the existing createIssue utility in src/utils/github.ts.
3. Verify the resulting gh --label arguments contain no duplicates.

Test strategy:

• Merge semantics match Task 2 (same helper or same pattern).
• The gh CLI invocation sees the merged label list with no duplicates.
• Omitting config + agent labels produces the existing behavior (no --label args).

---

Task 4 — Integration verification

Files to modify:

• New or extended integration tests under src/mcp/__tests__/ or the existing provider test locations

Implementation outline:

1. Add end-to-end merge-behavior tests for each provider: configure defaultLabels, invoke the MCP tool handler with agent-supplied labels, and assert the final label set delivered to the tracker adapter (Jira POST body; GitHub gh args) matches the expected merged list.
2. Add a regression test per provider: with defaultLabels unset or empty and no agent labels, no labels are attached.
3. Run pnpm build and pnpm test against the merged epic branch to confirm cross-task compatibility.

Test strategy:

• Parameterize merge-behavior scenarios (configured-only, input-only, both, overlapping, empty) across providers to avoid duplicated test logic.
• Treat this as the final gate before closing the epic.

---

Optional shared helper

If the merge logic appears identical in Tasks 2 and 3 (as expected), consider introducing a small utility:

// src/utils/labels.ts
export function mergeLabels(configured: string[] = [], supplied: string[] = []): string[] {
  const seen = new Set<string>()
  const out: string[] = []
  for (const label of [...configured, ...supplied]) {
    if (!seen.has(label)) {
      seen.add(label)
      out.push(label)
    }
  }
  return out
}

Introducing this in Task 2 or Task 3 (whichever lands first) keeps subsequent tasks thinner and ensures merge semantics stay consistent.

---

Suggested execution order

1. Merge Task 1 first — foundation for everything else, minimal risk.
2. Run Tasks 2 and 3 in parallel — independent files, same contract. Whichever lands first should introduce mergeLabels if the shared helper is chosen.
3. Run Task 4 after both wiring tasks merge — integration checks against the combined state.
4. Close epic Plan: Configurable default labels for issue tracker integrations #985 once Task 4's verification passes.

Risks and watch-outs

• Dual-schema update: forgetting to update IloomSettingsSchemaNoDefaults will silently break partial-settings validation. Grep for both schema names when editing SettingsManager.ts.
• Env-var fallback coverage: both the in-process settings read and the JIRA_DEFAULT_LABELS / GITHUB_DEFAULT_LABELS env-var fallback must be updated. Test both paths.
• Stale comment removal: Task 2 must delete the "labels not supported" comment in JiraIssueManagementProvider. A future reader seeing it beside working label code would be misled.
• GitHub label preexistence: gh errors on unknown labels. Docs should note that users must pre-create labels on their repo.
• Merge-order consistency: if a shared helper is not introduced, review both provider PRs together to confirm the merge algorithm matches exactly.