feat: add provider integration, cowork support, and three-tier instruction merge

- Add built-in provider instruction files (ticketing, spec, design, comms)
  with default behaviors for each phase of the AI-DLC workflow
- Implement three-tier instruction merge: built-in defaults → inline
  settings.yml instructions → project .ai-dlc/providers/{type}.md overrides
- Add provider context injection in session and subagent hooks
- Update elaborate skill with Phase 6.5 ticketing sync (epic/ticket
  creation, DAG → blocked-by mapping, existing epic support)
- Add cowork support with clone-first approach for non-repo environments
- Update builder/reviewer hats with SHOULD-level ticket status sync
- Expand settings schema with per-category provider type enums and
  instructions field
- Rename provider keys: ticketingProvider → ticketing, specProvider → spec,
  designProvider → design, commsProvider → comms

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: jwaldrip

examples/settings.yml

@@ -38,20 +38,25 @@ git:
 # Provider Configuration (optional)
 # Configure external system integrations for ticket sync, spec references, and more.
 # providers:
-#   specProvider:
-#     type: notion              # notion | confluence | google-docs
-#     config:
-#       workspace_id: "abc123"  # Optional provider-specific config
-#
-#   ticketingProvider:
+#   ticketing:
 #     type: jira                # jira | linear | github-issues | gitlab-issues
 #     config:
 #       project_key: "PROJ"
+#     instructions: |
+#       - Use Fibonacci story points (1, 2, 3, 5, 8, 13)
+#       - Always set component to "Backend" or "Frontend"
 #
-#   designProvider:
+#   design:
 #     type: figma               # figma
+#     instructions: |
+#       - Only reference designs marked "Ready for Dev"
+#
+#   spec:
+#     type: notion              # notion | confluence | google-docs
+#     config:
+#       workspace_id: "your-workspace-id"
 #
-#   commsProvider:
+#   comms:
 #     type: slack               # slack | teams | discord
 #     config:
-#       channel: "#engineering"
+#       channel: "#dev-updates"

plugin/hats/builder.md

@@ -39,6 +39,12 @@ The Builder implements code to satisfy the Unit's Completion Criteria, using bac
    - You SHOULD reference spec provider for API contracts if configured (endpoint definitions, data schemas)
    - **Validation**: Can enumerate what needs to be built
 
+#### Provider Sync — Ticket Status
+- If a `ticket` field exists in the current unit's frontmatter, **SHOULD** update the ticket status to **In Progress** using the ticketing provider's MCP tools
+- If the unit is completed successfully, **SHOULD** update the ticket to **Done**
+- If the unit is blocked, **SHOULD** flag the ticket as **Blocked** and add the blocker description as a comment
+- If MCP tools are unavailable, skip silently — never block building on ticket updates
+
 2. Implement incrementally
    - You MUST work in small, verifiable increments
    - You MUST run backpressure checks after each change

plugin/hats/reviewer.md

@@ -75,8 +75,14 @@ The Reviewer verifies that the Builder's implementation satisfies the Unit's Com
    - You MUST NOT approve if criteria are not met
    - You MUST NOT approve if configured testing requirements are not satisfied
    - **Validation**: Clear approve/reject with rationale
-   - You MAY update ticket status in ticketing provider if configured (mark as "in review" or "done")
-   - You MAY post completion summary to comms provider if configured (Slack/Teams notification)
+
+#### Provider Sync — Review Outcome
+- If a `ticket` field exists in the reviewed unit's frontmatter:
+  - **SHOULD** add the review outcome as a ticket comment (approved/rejected + summary)
+  - If **approving**: update ticket to **Done**
+  - If **rejecting**: keep ticket as **In Progress**, add rejection feedback as comment
+- **MAY** post a summary of the review outcome to the comms provider (if configured)
+- If MCP tools are unavailable, skip silently — never block review on provider sync
 
 ## Success Criteria
 

plugin/hooks/inject-context.sh

@@ -211,6 +211,17 @@ if [ -z "$ITERATION_JSON" ]; then
 
     echo "**To resume:** \`/resume <slug>\` or \`/resume\` if only one"
     echo ""
+    # Inject provider context for pre-elaboration awareness
+    CONFIG_LIB="${CLAUDE_PLUGIN_ROOT}/lib/config.sh"
+    if [ -f "$CONFIG_LIB" ]; then
+      # shellcheck source=/dev/null
+      source "$CONFIG_LIB"
+      PROVIDERS_MD=$(format_providers_markdown)
+      if [ -n "$PROVIDERS_MD" ]; then
+        echo "$PROVIDERS_MD"
+        echo ""
+      fi
+    fi
   else
     # No AI-DLC state and no resumable intents - show available workflows for /elaborate
     if [ -n "$AVAILABLE_WORKFLOWS" ]; then

plugin/hooks/subagent-context.sh

@@ -89,8 +89,9 @@ echo ""
 CONFIG_LIB="${CLAUDE_PLUGIN_ROOT}/lib/config.sh"
 if [ -f "$CONFIG_LIB" ]; then
   # shellcheck source=/dev/null
-  source "$CONFIG_LIB"
-  PROVIDERS_MD=$(format_providers_markdown)
+  source "$CONFIG_LIB" 2>/dev/null
+  export_ai_dlc_config 2>/dev/null
+  PROVIDERS_MD=$(format_providers_markdown 2>/dev/null)
   if [ -n "$PROVIDERS_MD" ]; then
     echo "$PROVIDERS_MD"
     echo ""

plugin/lib/config.sh

@@ -269,6 +269,49 @@ _provider_mcp_hint() {
   esac
 }
 
+# Load and merge provider instructions from three tiers
+# Usage: load_provider_instructions <category> <type> [inline_instructions]
+# Returns: Merged instruction text
+load_provider_instructions() {
+  local category="$1"  # ticketing, spec, design, comms
+  local type="$2"      # jira, notion, figma, slack, etc.
+  local inline_instructions="$3"  # from settings.yml, may be empty
+  local merged=""
+
+  # Tier 1: Built-in default
+  local builtin="${CLAUDE_PLUGIN_ROOT}/providers/${category}.md"
+  if [[ -f "$builtin" ]]; then
+    local body
+    body=$(awk '/^---$/{n++; next} n>=2' "$builtin")
+    merged="${body}"
+  fi
+
+  # Tier 2: Inline instructions from settings.yml
+  if [[ -n "$inline_instructions" ]]; then
+    merged="${merged}
+
+### Project-Specific Instructions (from settings.yml)
+${inline_instructions}"
+  fi
+
+  # Tier 3: Project override from .ai-dlc/providers/{type}.md
+  local repo_root
+  repo_root=$(find_repo_root 2>/dev/null || echo "")
+  if [[ -n "$repo_root" ]]; then
+    local override="${repo_root}/.ai-dlc/providers/${type}.md"
+    if [[ -f "$override" ]]; then
+      local override_body
+      override_body=$(awk '/^---$/{n++; next} n>=2' "$override")
+      merged="${merged}
+
+### Project Override (from .ai-dlc/providers/${type}.md)
+${override_body}"
+    fi
+  fi
+
+  printf '%s' "$merged"
+}
+
 # Detect VCS hosting platform from git remote
 # Usage: detect_vcs_hosting [directory]
 # Returns: github | gitlab | bitbucket | ''
@@ -310,7 +353,7 @@ detect_ci_cd() {
 # Returns: JSON object with all provider categories
 load_providers() {
   local repo_root="${1:-$(find_repo_root)}"
-  local result='{"specProvider":null,"ticketingProvider":null,"designProvider":null,"commsProvider":null,"vcsHosting":null,"ciCd":null}'
+  local result='{"spec":null,"ticketing":null,"design":null,"comms":null,"vcsHosting":null,"ciCd":null}'
 
   # Source 1: Declared providers from settings.yml
   if [ -n "$repo_root" ]; then
@@ -320,7 +363,7 @@ load_providers() {
       local providers
       providers=$(echo "$settings" | jq -c '.providers // {}')
       if [ "$providers" != "{}" ] && [ "$providers" != "null" ]; then
-        for key in specProvider ticketingProvider designProvider commsProvider; do
+        for key in spec ticketing design comms; do
           local val
           val=$(echo "$providers" | jq -c ".$key // null")
           if [ "$val" != "null" ]; then
@@ -335,7 +378,7 @@ load_providers() {
   local cached
   cached=$(han keep load providers.json --quiet 2>/dev/null || echo "")
   if [ -n "$cached" ] && [ "$cached" != "null" ]; then
-    for key in specProvider ticketingProvider designProvider commsProvider; do
+    for key in spec ticketing design comms; do
       local current
       current=$(echo "$result" | jq -c ".$key")
       if [ "$current" = "null" ]; then
@@ -373,7 +416,7 @@ format_providers_markdown() {
 
   # Check if anything is configured
   local has_any=false
-  for key in specProvider ticketingProvider designProvider commsProvider vcsHosting ciCd; do
+  for key in spec ticketing design comms vcsHosting ciCd; do
     local val
     val=$(echo "$providers" | jq -r ".$key // empty")
     if [ -n "$val" ] && [ "$val" != "null" ]; then
@@ -385,7 +428,7 @@ format_providers_markdown() {
   if [ "$has_any" = "false" ]; then
     echo "### Project Providers"
     echo ""
-    echo "No providers configured. Use \`ToolSearch\` to discover available MCP tools."
+    echo "No providers configured. Use \`ToolSearch\` to discover available MCP tools, or configure providers in \`.ai-dlc/settings.yml\`."
     return
   fi
 
@@ -413,7 +456,7 @@ format_providers_markdown() {
   fi
 
   # Declared providers
-  local categories="specProvider:Spec ticketingProvider:Ticketing designProvider:Design commsProvider:Comms"
+  local categories="spec:Spec ticketing:Ticketing design:Design comms:Comms"
   for entry in $categories; do
     local key="${entry%%:*}"
     local label="${entry##*:}"
@@ -430,4 +473,37 @@ format_providers_markdown() {
 
   echo ""
   echo "> **Tip:** Configure providers in \`.ai-dlc/settings.yml\` under \`providers:\` to enable automatic ticket sync and spec references."
+
+  # Provider Instructions section - merged from three tiers
+  local has_instructions=false
+  local category_map="ticketing:ticketing:Ticketing spec:spec:Spec design:design:Design comms:comms:Comms"
+  local instructions_output=""
+
+  for entry in $category_map; do
+    local key="${entry%%:*}"
+    local rest="${entry#*:}"
+    local category="${rest%%:*}"
+    local label="${rest##*:}"
+    local ptype
+    ptype=$(echo "$providers" | jq -r ".$key.type // empty")
+    if [ -n "$ptype" ]; then
+      local inline
+      inline=$(echo "$providers" | jq -r ".$key.instructions // empty")
+      local merged
+      merged=$(load_provider_instructions "$category" "$ptype" "$inline")
+      if [ -n "$merged" ]; then
+        has_instructions=true
+        instructions_output="${instructions_output}
+#### ${label} (${ptype})
+${merged}
+"
+      fi
+    fi
+  done
+
+  if [ "$has_instructions" = "true" ]; then
+    echo ""
+    echo "### Provider Instructions"
+    printf '%s' "$instructions_output"
+  fi
 }