lc-deployer

What this skill does

# LimaCharlie Agentic SOC & Agent Deployer

You help users deploy, install, and remove Agentic SOC as Code definitions (ai-team) and individual AI agents (ai-agents) in their LimaCharlie organizations.

---

## LimaCharlie Integration

> **Prerequisites**: Run `/init-lc` to initialize LimaCharlie context.

### LimaCharlie CLI Access

All LimaCharlie operations use the `limacharlie` CLI directly:

```bash
limacharlie <noun> <verb> --oid <oid> --output yaml [flags]
```

For command help and discovery: `limacharlie <command> --ai-help`

### Critical Rules

| Rule | Wrong | Right |
|------|-------|-------|
| **CLI Access** | Call MCP tools or spawn api-executor | Use `Bash("limacharlie ...")` directly |
| **Output Format** | `--output json` | `--output yaml` (more token-efficient) |
| **Filter Output** | Pipe to jq/yq | Use `--filter JMESPATH` to select fields |
| **OID** | Use org name | Use UUID (call `limacharlie org list` if needed) |

---

## Available Agents

Individual agents are defined in the `ai-agents/` directory of the lc-ai repository. Each agent has:
- A `README.md` describing what it does and its prerequisites
- A `hives/` directory containing the IaC YAML files to deploy

To discover available agents, list the directories under `ai-agents/` in the lc-ai repository.

## Available SOCs

Full SOC definitions are in the `ai-teams/` directory. Each SOC is a coordinated set of agents that work together:

| SOC | Agents | Description |
|-----|--------|-------------|
| `lean-soc` | 4 agents | Minimal SOC: triage, investigator, responder, reporter |
| `tiered-soc` | 8 agents | Full L1/L2/L3 SOC: triage, l1-investigator, l2-analyst, malware-analyst, containment, threat-hunter, soc-manager, shift-reporter |
| `baselining-soc` | 7 agents | Noise-reduction SOC for new orgs: bulk-triage, l2-analyst, malware-analyst, containment, threat-hunter, soc-manager, shift-reporter |

Each SOC has a top-level `README.md` describing its architecture, cost profile, and tradeoffs. Each agent within the SOC has its own `README.md` with specific API key permissions.

To discover available SOCs, list the directories under `ai-teams/` in the lc-ai repository.

### Tag Convention

Every `ai_agent` hive record in a SOC carries two kinds of tags:

| Tag Type | Format | Example |
|----------|--------|---------|
| **Identity** | `ai-team:<soc-name>:<role>` | `ai-team:tiered-soc:l1-investigator` |
| **Relationship** | `ai-team:<soc-name>:sends-to:<target-role>` | `ai-team:tiered-soc:sends-to:l2-analyst` |
| **API Key** | `ai-team:api-key:<agent-name>` | `ai-team:api-key:soc-l1-investigator` |

- The **identity tag** names the agent's role within the SOC.
- Each **`sends-to` tag** declares a directed edge: this agent's output feeds `<target-role>` (via D&R trigger, case escalation, or data dependency).
- The **`api-key` tag** names the agent whose LimaCharlie API key secret is in `hive://secret/<agent-name>`. The secret name matches the agent's hive key. This is SOC-independent: shared agents carry one `api-key` tag regardless of how many SOCs reference them.
- Schedule-only agents with no downstream consumers (reporter, soc-manager, shift-reporter) have an identity tag but no `sends-to` tags.
- Terminal agents (responder, containment) also have no `sends-to` tags.

**Reconstructing the flow graph**: List all `ai_agent` records, parse identity tags as nodes, parse `sends-to` tags as directed edges, and group by SOC name. This works even when multiple SOCs coexist in the same org because the SOC name is embedded in every tag.

**Multi-SOC coexistence**: When tiered-soc and baselining-soc are installed in the same org, some agents share the same hive key (e.g., `soc-l2-analyst`). Each SOC contributes its own identity and `sends-to` tags, so the record carries tags from both SOCs simultaneously. See the "Install a SOC" section for the tag-merging procedure.

---

## Install an Agent

When the user asks to install/deploy an agent, follow these steps:

### Step 1: Read the Agent Definition

Read the agent's `README.md` and all files in its `hives/` directory to understand:
- What the agent does
- What extensions it requires
- What secrets it needs
- What hive entries it creates (ai_agent, dr-general, etc.)

The agent definitions are in the `ai-agents/` directory at the root of the lc-ai repository. The lc-ai repo is the marketplace source for this plugin, so find it by searching for it relative to the plugin installation:

```bash
# The ai-agents dir is 3 levels up from this skill's directory
# (skills/lc-deployer/ -> skills/ -> lc-advanced-skills/ -> plugins/ -> marketplace/ -> repo root)
find / -path "*/lc-ai/ai-agents" -type d 2>/dev/null | head -1
```

Read all hive YAML files for the agent to understand the full configuration.

### Step 2: Get the Target OID

Ask the user which organization to install into, or use the OID they provided.
Verify with:
```bash
limacharlie org list --output yaml
```

### Step 2b: Verify Permissions

Before proceeding, verify the current credentials have the `ai_agent.operate` permission (required for all agent deployments).
**IMPORTANT**: You MUST include `--oid <oid>` — without it, the check runs against a null org context and will always return `has_perm: false`:
```bash
limacharlie auth whoami --oid <oid> --check-perm ai_agent.operate --output yaml
```
If `has_perm: false`, stop and inform the user their API key or user account lacks this permission.

### Step 3: Subscribe to Required Extensions

Check the agent's README for required extensions. Subscribe to each:
```bash
limacharlie extension subscribe --name <extension-name> --oid <oid>
```

Common extensions for agents:
- `ext-cases` - Required for case-based agents

Check if already subscribed first:
```bash
limacharlie extension list --oid <oid> --output yaml
```

### Step 4: Set Up Secrets

Each agent has a `secret.yaml` defining required secrets. For each secret:

#### LimaCharlie API Key

Offer to create the API key for the user automatically:

Mint the key and store its value as a secret in a single atomic step with `--store-secret`. The secret name **must equal the agent's hive key** (what the agent's `ai_agent.yaml` references in `lc_api_key_secret`, e.g. `hive://secret/<agent-name>` means the secret key is `<agent-name>`):

```bash
limacharlie api-key create \
  --name "<agent-name>" \
  --permissions "sensor.list,sensor.get,sensor.task,dr.list,dr.set,org.get,hive.get,ext.request,org_notes.get,org_notes.set,ai_agent.operate" \
  --store-secret <agent-name> \
  --oid <oid> \
  --output yaml
```

`--store-secret` writes the key value to `hive://secret/<agent-name>` created **enabled** (and updates it via etag if the secret already exists), so you never have to capture and re-store the value manually.

Adjust permissions based on what the agent needs. For case-based agents, also include permissions for cases operations.

**Fallback (manual two-step)**: if `--store-secret` is unavailable, create the key, capture the value (it is only shown once), then store it with `enabled: true`:

```bash
echo '{"data": {"secret": "<the-api-key-value>"}, "usr_mtd": {"enabled": true}}' | limacharlie hive set --hive-name secret --key <agent-name> --oid <oid>
```

#### Anthropic API Key (`anthropic-key`)

Ask the user for their Anthropic API key. Then store it:

```bash
echo '{"data": {"secret": "<user-provided-key>"}, "usr_mtd": {"enabled": true}}' | limacharlie hive set --hive-name secret --key anthropic-key --oid <oid>
```

**NEVER** generate, guess, or fabricate API keys. The user must provide their own Anthropic key.

#### Other Secrets

If the agent requires additional secrets, ask the user for the values.

### Step 5: Push the Hive Configurations

Each agent has a root IaC file (e.g., `basic-triage.yaml`) that uses `include:` to pull in all its hive configs. Push it with a single command:

```bash
limacharlie sync push \
  --config-file <path-to-agent>/<agent-name>.yaml \
  --hive-ai-agent \