story-config-resolver

story-config-resolver

Resolves the active configuration for the Story coding agent by layering multiple sources in a defined precedence order and enforcing governance constraints before any implementation 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 story-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 sprint/sprint-jira/.claude-plugin/plugin.json.

If sprint-jira is not detected:

• Halt immediately with:

  ERROR: sprint-jira module is required for ticket normalisation and domain classification but is not installed.
  Install it: claude plugin install @Vensure-Devops-QA/sprint-jira
  /story-implement will fail without this module.
  

• Do not proceed. This is a hard prerequisite.

If sprint-jira is detected:

• Continue with board MCP availability check below.

Board MCP Availability Check

Read boardSource directly from .story-agent.json (raw file read, before full 5-level resolution). If the file does not exist or boardSource is absent, skip this check and set storyBoardAvailable: false.

After the sprint-jira check, determine boardSource from the resolved .story-agent.json config and check whether the appropriate MCP server is configured.

MCP detection mechanism: Read .mcp.json in the workspace root using the Read tool. If not found there, read ~/.claude/mcp.json. Search the mcpServers object for an entry whose key matches:

boardSource	Accepted server name patterns
"jira"	jira, atlassian-jira, atlassian
"ado"	azure-devops, ado, azuredevops

If a matching entry is found:

• Set storyBoardAvailable: true in the output

If no matching entry is found:

• Set storyBoardAvailable: false in the output
• Emit a non-blocking warning:

  WARNING: Board MCP server ({boardSource}) not found in .mcp.json or ~/.claude/mcp.json.
  Add the MCP server entry and retry. /story-implement will fail at ticket-fetch if MCP is unavailable.
  

• Continue with config resolution.

Configuration File

Read .story-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 /story-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., --confidence 0.7, inline @config blocks)
2. Directory mapping — directoryMapping entries in .story-agent.json matched against the current working path
3. Auto-detection — env vars (JIRA_BASE_URL, JIRA_API_TOKEN, JIRA_EMAIL, ADO_ORG_URL, ADO_PAT) present in the process environment; note that JIRA_BASE_URL and ADO_ORG_URL are stored in resolved config, while JIRA_EMAIL, JIRA_API_TOKEN, and ADO_PAT are credentials passed to board-connector at runtime (not stored)
4. Config defaults — top-level values in .story-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 board-connector at runtime (not stored)
JIRA_API_TOKEN	Passed to board-connector at runtime (not stored)
ADO_ORG_URL	ado.orgUrl
ADO_PAT	Passed to board-connector at runtime (not stored)

Plugin Defaults

When neither config file nor auto-detection provides a value, fall back to:

Field	Default
outputDir	. (workspace root)
execution.confidenceThreshold	0.6
execution.requireApproval	true
execution.dependencyOrder	["db-coding-agent", "backend-coding-agent", "frontend-coding-agent", "devops-coding-agent", "security-coding-agent"]

Governance Enforcement

After resolving config, enforce:

Approved Domain Agents

If governance.approvedDomainAgents is set, this list is used by domain-router to warn (not halt) when a ticket would be routed to an unapproved agent.

Org Policy Endpoint

If governance.orgPolicyEndpoint is configured, fetch org policy before any implementation begins (called once, cached for the session):

Request:

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

orgPolicyToken substitution: The value "${ORG_POLICY_TOKEN}" in .story-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
HTTP 200 + "allowed": true	Merge returned overrides over local config (org wins on conflict)

Output

Emit the resolved configuration as structured data before proceeding:

{
  "boardSource": "ado",
  "ado": {
    "orgUrl": "https://dev.azure.com/your-org",
    "project": "MyProject",
    "teamId": "my-team"
  },
  "labelMappings": { "backend": [...], "frontend": [...], "database": [...], "devops": [...], "security": [...] },
  "outputDir": ".",
  "execution": {
    "confidenceThreshold": 0.6,
    "requireApproval": true,
    "dependencyOrder": ["db-coding-agent", "backend-coding-agent", "frontend-coding-agent", "devops-coding-agent", "security-coding-agent"]
  },
  "governance": {
    "approvedDomainAgents": [...],
    "orgPolicyEndpoint": "<url-or-null>",
    "guardrailsActive": true
  },
  "storyBoardAvailable": true,
  "resolutionSource": {
    "boardSource": "config-defaults",
    "ado.orgUrl": "config-defaults",
    "ado.project": "config-defaults",
    "execution.confidenceThreshold": "plugin-defaults"
  }
}

When boardSource: 'jira', the ado key is omitted from the output and the jira block appears instead.

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