Integrate Unleash with Kiro

1
---
2
inclusion: always
3
---
4
5
# Feature Flag Conventions
6
7
When making changes to this codebase, follow these feature flag practices:
8
9
1. **Always evaluate risk**: Before implementing high-risk changes (payments,
10
   authentication, data migrations, external integrations), use the Unleash MCP
11
   server to evaluate whether a feature flag is needed.
12
13
2. **Naming conventions**: Use the format `{domain}-{feature}-{variant}`.
14
   Examples: `checkout-stripe-integration`, `auth-sso-google`, `api-rate-limiting`.
15
16
3. **Flag types**:
17
   - `release`: For gradual feature rollouts
18
   - `experiment`: For A/B tests and experiments
19
   - `operational`: For system behavior toggles
20
   - `kill-switch`: For emergency shutdowns
21
   - `permission`: For role-based access
22
23
4. **Prefer reuse**: Before creating a new flag, check if a similar flag already
24
   exists using the detect_flag tool.
25
26
5. **Clean up after rollout**: Once a feature is fully released (100% rollout for
27
   2+ weeks), use cleanup_flag to remove dead code.
28
29
## Unleash MCP Server
30
31
This project uses the Unleash MCP server for feature flag management. Configuration
32
is in `.kiro/settings/mcp.json`. Credentials are sourced from environment variables.
33
34
Available tools: evaluate_change, detect_flag, create_flag, wrap_change,
35
get_flag_state, set_flag_rollout, toggle_flag_environment, remove_flag_strategy,
36
cleanup_flag.

1
---
2
inclusion: fileMatch
3
fileMatchPattern: ["src/payments/**/*.ts", "src/payments/**/*.tsx"]
4
---
5
6
# Payments Domain — Feature Flag Policy
7
8
All changes in the payments domain require feature flags. No exceptions.
9
10
- Use `kill-switch` type for external payment provider integrations
11
  (Stripe, PayPal, etc.)
12
- Use `release` type for internal payment logic changes
13
- Naming: `payments-{feature}-{variant}`
14
  (e.g., `payments-stripe-checkout`, `payments-refund-v2`)
15
- Always include a fallback path for external provider calls
16
- Evaluate risk with evaluate_change before writing implementation code

1
---
2
inclusion: auto
3
name: rollout-guidance
4
description: Guidance for configuring feature flag rollout strategies. Use when
5
  setting up rollouts, configuring milestones, or discussing gradual releases.
6
---
7
8
# Rollout Strategy Defaults
9
10
When setting up rollouts with set_flag_rollout, use these defaults unless
11
specified otherwise:
12
13
- Start at 10% rollout
14
- Wait 24 hours before advancing
15
- Pause if error rate exceeds 1% or p95 latency increases by more than 20%
16
17
## Standard milestones
18
19
| Milestone | Percentage | Hold period | Advance condition |
20
|-----------|-----------|-------------|-------------------|
21
| Canary | 10% | 24 hours | Error rate < 1%, latency stable |
22
| Beta | 50% | 48 hours | Error rate < 0.5%, no regressions |
23
| GA | 100% | — | All metrics healthy for 48 hours |
24
25
## Cleanup cadence
26
27
Run cleanup_flag weekly for flags that have been at 100% for more than 14 days.

1
{
2
  "enabled": true,
3
  "name": "Evaluate payments changes for feature flags",
4
  "description": "Automatically evaluates whether saved changes in the payments domain should be behind a feature flag",
5
  "version": "1",
6
  "when": {
7
    "type": "fileSave",
8
    "filePattern": "src/payments/**/*.ts"
9
  },
10
  "then": {
11
    "type": "askAgent",
12
    "prompt": "The file $FILE_PATH was just saved with changes in the payments domain. Use the Unleash MCP server's evaluate_change tool to determine if these changes should be behind a feature flag. If yes, suggest a flag name following our payments naming convention (payments-{feature}-{variant}) and offer to create it."
13
  }
14
}

1
{
2
  "enabled": true,
3
  "name": "Feature flag audit",
4
  "description": "Run an audit of all feature flags, identifying stale flags and cleanup opportunities",
5
  "version": "1",
6
  "when": {
7
    "type": "userTriggered"
8
  },
9
  "then": {
10
    "type": "askAgent",
11
    "prompt": "Run a comprehensive feature flag audit using the Unleash MCP server. For each flag in the default project: 1) Use get_flag_state to check its current state, 2) Identify flags at 100% rollout for more than 14 days, 3) Identify flags that haven't been modified in 90 days, 4) Generate a prioritized cleanup report with recommendations for each stale flag."
12
  }
13
}

1
---
2
name: "unleash"
3
displayName: "Unleash Feature Flags"
4
description: "Automate feature flag management with Unleash. Evaluate code changes for risk, create flags with consistent naming, generate SDK wrapping code, manage rollouts, and clean up stale flags."
5
keywords: ["feature flag", "feature toggle", "rollout", "unleash", "release", "experiment", "kill-switch", "canary", "progressive delivery", "featureops"]
6
---
7
8
# Onboarding
9
10
## Step 1: Verify prerequisites
11
12
- **Node.js 18+**: Verify with `node --version`
13
- **Unleash instance**: Cloud or self-hosted, with API access
14
- **Personal Access Token**: With permissions to create and manage flags
15
16
## Step 2: Set environment variables
17
18
Create a credentials file and source it from your shell profile:
19
20
\`\`\`bash
21
mkdir -p ~/.unleash
22
cat > ~/.unleash/mcp.env << 'EOF'
23
UNLEASH_BASE_URL=https://your-instance.getunleash.io
24
UNLEASH_PAT=your-personal-access-token
25
UNLEASH_DEFAULT_PROJECT=default
26
EOF
27
chmod 600 ~/.unleash/mcp.env
28
\`\`\`
29
30
Add to `~/.zshrc` or `~/.bashrc`:
31
32
\`\`\`bash
33
if [ -f ~/.unleash/mcp.env ]; then
34
  source ~/.unleash/mcp.env
35
  export UNLEASH_BASE_URL UNLEASH_PAT UNLEASH_DEFAULT_PROJECT
36
fi
37
\`\`\`
38
39
## Step 3: Add hooks (optional)
40
41
Save a File Save hook to `.kiro/hooks/evaluate-payments-flag.kiro.hook`
42
to automatically evaluate payments changes. Adjust the `filePattern` to
43
match your project's high-risk directories.
44
45
# When to Load Steering Files
46
47
- Setting up feature flags → `feature-flag-conventions.md`
48
- Configuring rollout strategies → `rollout-guidance.md`
49
- Cleaning up stale flags → `cleanup-cadence.md`

1
{
2
  "mcpServers": {
3
    "unleash": {
4
      "command": "npx",
5
      "args": ["-y", "@unleash/mcp@latest", "--log-level", "error"],
6
      "env": {
7
        "UNLEASH_BASE_URL": "${UNLEASH_BASE_URL}",
8
        "UNLEASH_PAT": "${UNLEASH_PAT}",
9
        "UNLEASH_DEFAULT_PROJECT": "${UNLEASH_DEFAULT_PROJECT}"
10
      },
11
      "autoApprove": ["get_flag_state", "detect_flag", "evaluate_change", "list_projects", "list_flags"]
12
    }
13
  }
14
}