sprint-config-resolver

sprint-config-resolver

Resolves the active configuration for the Sprint coding agent by layering multiple sources in a defined precedence order and enforcing governance constraints before any planning action begins.

Guardrails Prerequisite Check

Before any other check, inspect the workspace root for .guardrails-agent.json.

If .guardrails-agent.json exists:

• Set internal flag guardrailsActive: true
• Delegate input/output validation, harm prevention, and audit trail to sprint-guardrails adapter skill
• Continue with config resolution below

If .guardrails-agent.json does not exist:

• Halt immediately with:

  ERROR: guardrails-coding-agent is required but not installed.
  Install it: claude plugin install @Vensure-Devops-QA/guardrails-coding-agent
  Then run:   /guardrails-db-init
  

• Do not proceed. This is a hard prerequisite.

Sprint-Jira Module Check

After the guardrails check, verify the sprint-jira module is installed by checking for the presence of the sprint-jira plugin directory (any of: sprint/sprint-jira, or a sprint-jira entry in the local plugin registry).

If sprint-jira is not detected:

• Emit a warning: "WARNING: sprint-jira module not found. Jira connectivity will be unavailable. Install it: claude plugin install @Vensure-Devops-QA/sprint-jira"
• Proceed with config resolution but mark sprintJiraAvailable: false in the output

If sprint-jira is detected:

• Set sprintJiraAvailable: true in the output

Sprint-ADO Module Check

After the sprint-jira check, verify the sprint-ado module is installed by checking for the presence of the sprint-ado plugin directory (any of: sprint/sprint-ado, or a sprint-ado entry in the local plugin registry).

If sprint-ado is not detected:

• Set sprintAdoAvailable: false in the output

If sprint-ado is detected:

• Set sprintAdoAvailable: true in the output

Active Connector Detection

After both module checks, determine which connector is active by inspecting the resolved config:

Config state	activeConnector
ado block present	"ado"
jira block present, no ado	"jira"
Both jira and ado blocks present	"ado" — emit warning: "Both jira and ado blocks found in .sprint-agent.json — ado takes precedence."
Neither block present	null — halt immediately: "No connector configured. Add a jira or ado block to .sprint-agent.json and run /sprint-init."

Configuration File

Read .sprint-agent.json from the workspace root if it exists. This file is optional at the filesystem level but its absence means most fields fall back to plugin defaults. Parse as JSON and surface a clear error if the file is present but malformed.

The file is typically created by the /sprint-init command.

Resolution Order

Apply the following five-level priority chain. Higher levels fully override lower levels for the same key. Merge objects at the same key rather than replacing them.

1. Per-invocation override — options passed directly in the current prompt (e.g., "use board 99", inline @config blocks)
2. Directory mapping — directoryMapping entries in .sprint-agent.json matched against the current working path
3. Auto-detection — env vars (JIRA_BASE_URL, JIRA_API_TOKEN, JIRA_EMAIL) present in the process environment
4. Config defaults — top-level values in .sprint-agent.json
5. Plugin defaults — hard-coded fallbacks bundled with the core plugin

Auto-Detection

When no higher-priority source specifies a value, check the process environment:

Env Var	Resolved Field
JIRA_BASE_URL	jira.baseUrl
JIRA_EMAIL	Passed to jira-connector
JIRA_API_TOKEN	Passed to jira-connector
ADO_ORG_URL	ado.orgUrl
ADO_PAT	Passed to ado-connector at runtime

Governance Enforcement

After resolving config, enforce:

Approved Domain Agents

If governance.approvedDomainAgents is set, verify each agent name against the approved list before routing. If a ticket would be routed to an unapproved agent, include a warning in the plan output rather than halting.

Org Policy Endpoint

If governance.orgPolicyEndpoint is configured, fetch org policy at session start (called once by the SessionStart hook, cached for the session):

Request:

GET {orgPolicyEndpoint}
Authorization: Bearer {orgPolicyToken}
X-Plugin-Name: sprint-coding-agent
X-Plugin-Version: 1.0.0

orgPolicyToken substitution: The value "${ORG_POLICY_TOKEN}" in .sprint-agent.json is a placeholder. At runtime, config-resolver reads the literal string, detects the ${...} pattern, and substitutes the value from the process environment (ORG_POLICY_TOKEN). If the env var is unset, the token is omitted from the request header.

Response handling:

Condition	Behaviour
Timeout > 5s or HTTP 5xx	Fail-closed — halt with: "Cannot reach org policy endpoint. Contact your admin."
HTTP 4xx	Warn and proceed
HTTP 200 + "allowed": false	Halt with the reason from the response body, or "Sprint planning blocked by org policy." if reason is null
HTTP 200 + "allowed": true	Merge returned overrides over local config (org wins on conflict)

Response schema:

{
  "allowed": true,
  "reason": null,
  "overrides": {
    "approvedDomainAgents": ["backend-coding-agent", "frontend-coding-agent"]
  }
}

Output

Emit the resolved configuration as structured data before proceeding:

{
  "jira": {
    "baseUrl": "https://your-org.atlassian.net",
    "boardId": 42,
    "projectKey": "PROJ"
  },
  "ado": null,
  "labelMappings": { "backend": [...], "frontend": [...], "database": [...], "devops": [...], "security": [...] },
  "outputDir": ".",
  "governance": {
    "approvedDomainAgents": [...],
    "orgPolicyEndpoint": "<url-or-null>",
    "guardrailsActive": true
  },
  "sprintJiraAvailable": true,
  "sprintAdoAvailable": false,
  "activeConnector": "jira",
  "resolutionSource": {
    "jira.baseUrl": "config-defaults",
    "jira.boardId": "config-defaults",
    "labelMappings": "config-defaults",
    "activeConnector": "config-defaults"
  }
}

resolutionSource records which level provided each value, for transparency and debugging.