[REL-12454] supporting approvals

skills/ai-configs/aiconfig-projects/README.md

@@ -61,7 +61,7 @@ aiconfig-projects/
 
 ## Related
 
-- [LaunchDarkly AI Configs](https://docs.launchdarkly.com/home/ai-configs) — Create AI Configs after setting up projects
+- [LaunchDarkly AI Configs](https://docs.launchdarkly.com/home/ai-configs): Create AI Configs after setting up projects
 - [LaunchDarkly Docs](https://docs.launchdarkly.com)
 - [Agent Skills Specification](https://agentskills.io/specification)
 

skills/ai-configs/aiconfig-projects/SKILL.md

@@ -22,15 +22,15 @@ You're using a skill that will guide you through setting up LaunchDarkly project
 1. **Understand First**: Explore the codebase to understand the stack and patterns.
 2. **Choose the Right Fit**: Select an approach that matches your architecture.
 3. **Follow Conventions**: Respect existing code style and structure.
-4. **Verify Integration**: Confirm the setup works — the agent performs checks and reports results.
+4. **Verify Integration**: Confirm the setup works: the agent performs checks and reports results.
 
 ## API Key Detection
 
 Before prompting the user for an API key, try to detect it automatically:
 
-1. **Check environment variables** — Look for `LAUNCHDARKLY_API_KEY`, `LAUNCHDARKLY_API_TOKEN`, or `LD_API_KEY`
-2. **Check MCP config** — If using Claude, read `~/.claude/config.json` for `mcpServers.launchdarkly.env.LAUNCHDARKLY_API_KEY`
-3. **Prompt user** — Only if detection fails, ask the user for their API key
+1. **Check environment variables**: Look for `LAUNCHDARKLY_API_KEY`, `LAUNCHDARKLY_API_TOKEN`, or `LD_API_KEY`
+2. **Check MCP config**: If using Claude, read `~/.claude/config.json` for `mcpServers.launchdarkly.env.LAUNCHDARKLY_API_KEY`
+3. **Prompt user**: Only if detection fails, ask the user for their API key
 
 See [Quick Start](references/quick-start.md) for API usage patterns.
 

skills/feature-flags/launchdarkly-flag-targeting/SKILL.md

@@ -25,6 +25,9 @@ This skill requires the remotely hosted LaunchDarkly MCP server to be configured
 
 **Optional MCP tools:**
 - `copy-flag-config`: copy targeting configuration from one environment to another
+- `create-approval-request`: create an approval request when direct changes are blocked
+- `list-approval-requests`: check on pending approval requests for a flag
+- `apply-approval-request`: apply an already-approved approval request
 
 ## Core Concept: Evaluation Order
 
@@ -74,7 +77,12 @@ Based on what the user wants and what you found, choose the right tool and strat
 Before applying changes, especially in production, run through the [Safety Checklist](references/safety-checklist.md). The key checks:
 
 1. **Right environment?** Double-check you're targeting the intended environment.
-2. **Approval required?** Some environments require approval workflows. If `toggle-flag` or other tools return `requiresApproval: true`, surface this to the user with the approval URL.
+2. **Approval required?** Some environments require approval workflows. If any mutation tool returns `requiresApproval: true`:
+   - Inform the user that this environment requires approvals.
+   - Share the `approvalUrl` if provided.
+   - Offer to create an approval request using `create-approval-request` with the same instructions (returned in the `instructions` field of the response).
+   - Do NOT attempt to bypass approval or auto-approve.
+   - See [Approval Workflows](references/approval-workflows.md) for the full process.
 3. **Prerequisite flags?** If this flag has prerequisites, they must be met before targeting works as expected.
 4. **Rule ordering impact?** If adding rules, consider where they fall in evaluation order. Rules evaluate top-to-bottom, first match wins.
 5. **Include a comment.** Always add an audit trail comment, especially for production changes.
@@ -100,6 +108,16 @@ After applying changes, confirm the result:
    - "Beta users now see variation A. Everyone else gets the default (variation B)."
 3. **Check for side effects.** If there are rules or individual targets, make sure the change interacts correctly with them.
 
+### Handling Approval-Required Environments
+
+When any mutation tool returns `requiresApproval: true`, the direct change was blocked because the environment requires approvals. Follow the [Approval Workflows](references/approval-workflows.md) reference to:
+
+1. **Create an approval request** with `create-approval-request` using the `instructions` from the blocked response
+2. **Inform the user** about the pending approval and share the approval request details
+3. **Check on approval status** later with `list-approval-requests` if requested
+4. **Apply the request** with `apply-approval-request` once a reviewer has approved it (reviewStatus is "approved")
+5. **Verify the result** with `get-flag` after applying
+
 ## Important Context
 
 - **`update-rollout` uses human-friendly percentages.** Pass 80 for 80%, not 80000. The tool handles the internal weight conversion.
@@ -112,3 +130,4 @@ After applying changes, confirm the result:
 
 - [Targeting Patterns](references/targeting-patterns.md): Rollout strategies, rule construction, individual targeting, and cross-environment copying
 - [Safety Checklist](references/safety-checklist.md): Pre-change verification, approval workflows, environment awareness
+- [Approval Workflows](references/approval-workflows.md): Creating, checking, and applying approval requests

skills/feature-flags/launchdarkly-flag-targeting/marketplace.json

@@ -1,6 +1,6 @@
 {
   "name": "launchdarkly-flag-targeting",
-  "description": "Control LaunchDarkly feature flag targeting including toggling, rollouts, rules, individual targets, and cross-environment copying",
+  "description": "Control LaunchDarkly feature flag targeting including toggling, rollouts, rules, individual targets, cross-environment copying, and approval workflows",
   "version": "1.0.0-experimental",
   "author": "LaunchDarkly",
   "repository": "https://github.com/launchdarkly/agent-skills",

skills/feature-flags/launchdarkly-flag-targeting/references/approval-workflows.md

@@ -0,0 +1,116 @@
+# Approval Workflows
+
+Some LaunchDarkly environments require approval before changes take effect. This is an Enterprise feature configured per environment. When this happens, mutation tools like `toggle-flag`, `update-rollout`, `update-targeting-rules`, `update-individual-targets`, and `copy-flag-config` return `requiresApproval: true` instead of making the change directly.
+
+## Detecting Approval Requirements
+
+Any mutation tool response may include these fields when a change is blocked:
+
+- `requiresApproval: true`: the change was blocked and needs approval
+- `approvalUrl`: a URL where the approval can be reviewed (if available)
+- `message`: a human-readable explanation
+- `instructions`: the semantic patch instructions that were attempted (use these to create an approval request)
+
+## Creating an Approval Request
+
+When a change is blocked, use `create-approval-request` to submit the change for review:
+
+1. Use the **same instructions** returned in the blocked response's `instructions` field
+2. Provide a clear `description` explaining what the change does and why
+3. Optionally notify specific team members (`notifyMemberIds`) or teams (`notifyTeamKeys`)
+
+### Example: Toggle flag with approval
+
+If `toggle-flag` returns `requiresApproval: true`:
+
+```
+Tool: create-approval-request
+Input:
+  projectKey: "my-project"
+  flagKey: "new-checkout"
+  env: "production"
+  instructions: [{"kind": "turnFlagOn"}]
+  description: "Enable new checkout flow in production after successful staging test"
+```
+
+### Example: Rollout with approval
+
+If `update-rollout` returns `requiresApproval: true` with instructions:
+
+```
+Tool: create-approval-request
+Input:
+  projectKey: "my-project"
+  flagKey: "new-checkout"
+  env: "production"
+  instructions: [{"kind": "updateFallthroughVariationOrRollout", "rolloutWeights": {"var-id-1": 25000, "var-id-2": 75000}}]
+  description: "Roll out new checkout to 25% of users in production"
+```
+
+### Example: Targeting rule with approval
+
+If `update-targeting-rules` returns `requiresApproval: true`:
+
+```
+Tool: create-approval-request
+Input:
+  projectKey: "my-project"
+  flagKey: "new-checkout"
+  env: "production"
+  instructions: [{"kind": "addRule", "clauses": [{"contextKind": "user", "attribute": "email", "op": "endsWith", "values": ["@company.com"]}], "variationId": "<variation-id>", "description": "Internal users"}]
+  description: "Add targeting rule for internal users in production"
+```
+
+## Checking Approval Status
+
+Use `list-approval-requests` to see pending requests for a flag:
+
+```
+Tool: list-approval-requests
+Input:
+  projectKey: "my-project"
+  flagKey: "new-checkout"
+  env: "production"
+```
+
+The response shows:
+- `status`: pending, completed, or failed
+- `reviewStatus`: pending, approved, or declined
+- `reviews`: list of reviewer actions with status and comments
+- `description`: what the change does
+- `instructionCount`: number of instructions in the request
+
+## Applying Approved Requests
+
+Once a reviewer approves the request (`reviewStatus` is `"approved"`), use `apply-approval-request`:
+
+```
+Tool: apply-approval-request
+Input:
+  projectKey: "my-project"
+  id: "<approval-request-id>"
+  comment: "Applying approved production rollout"
+```
+
+After applying, verify the change with `get-flag`.
+
+**Important:** The agent can apply already-approved requests but must NEVER approve requests itself. Approval is a human decision.
+
+## What the Agent Should NOT Do
+
+- **Do NOT auto-approve**: The purpose of approvals is human oversight. Never try to approve a request.
+- **Do NOT retry the direct change**: If a change was blocked, retrying the same mutation will also be blocked. Use the approval workflow.
+- **Do NOT skip informing the user**: Always tell the user that approval is required and what the next steps are.
+- **Do NOT bypass approval**: Never use workarounds or alternative API calls to skip the approval process.
+
+## Typical Flow
+
+1. User asks for a targeting change (e.g., "turn on the flag in production")
+2. Agent attempts the change using the mutation tool
+3. Tool returns `requiresApproval: true` with `instructions`
+4. Agent informs the user and offers to create an approval request
+5. If the user agrees, agent creates the request with `create-approval-request`
+6. Agent shares the approval request details (ID, approval URL if available)
+7. A human reviewer approves or declines the request (outside the agent)
+8. If approved, the user or agent can apply it with `apply-approval-request`
+9. Agent verifies the change with `get-flag`

skills/feature-flags/launchdarkly-flag-targeting/references/safety-checklist.md

@@ -24,9 +24,15 @@ Run through this checklist before applying any targeting changes, especially in
 
 Some environments require approval for changes.
 
-- [ ] If the API returns `requiresApproval: true`, inform the user
-- [ ] Provide the approval URL so they can follow the workflow
-- [ ] Do NOT attempt to bypass approval
+- [ ] If any mutation tool returns `requiresApproval: true`, inform the user
+- [ ] Provide the approval URL if one was returned
+- [ ] Offer to create an approval request with `create-approval-request` using the returned `instructions`
+- [ ] Include a clear description of the intended change in the approval request
+- [ ] Do NOT attempt to bypass approval or auto-approve
+- [ ] If checking on a previous request, use `list-approval-requests`
+- [ ] Only apply a request (`apply-approval-request`) if reviewStatus is "approved"
+
+See [Approval Workflows](approval-workflows.md) for the complete reference.
 
 ### 5. Audit Trail