---
description: >
  Use when the user says "set up data for HawkScan", "my scan has no data to hit", "seed this repo for scanning", or as a first-time-setup step before invoking hawkscan on a fresh repo. Drives the 'hawk perch seed' CLI command, which reads the target repo, designs the minimum seed entities for authenticated scanning, and emits reviewed artifacts under data-seed/ (SQL / HTTP / gRPC / Mongo / shell scripts, a manifest.yaml, and a .data-seed-credentials.env handoff). The seed methodology lives in the hawk CLI; this skill drives the command and relays its JSONL progress. Does NOT write stackhawk.yml (hawkscan owns that). NOT autonomous — explicit user invocation only.
globs:
  - "**/data-seed/manifest.yaml"
  - "**/.data-seed-credentials.env"
alwaysApply: false
---

# StackHawk Data Seed Skill

This skill produces checked-in, reproducible seed-data artifacts for a target repo so authenticated HawkScan finds non-empty results. The synthesis logic lives in the `hawk` CLI (`hawk perch seed`); this skill drives that command and relays its progress to the user. It works the same across every agent that can run a subprocess and read its output.

It does NOT run the artifacts, start the environment, or write `stackhawk.yml` — those belong to the human, the user's tooling, and the `hawkscan` skill respectively.

---

## When to Run

Invoke explicitly when:

- User says "set up data for HawkScan" / "seed this repo" / "my scan has no data to hit."
- Configuring HawkScan against a repo for the first time and the app needs authenticated routes to scan.
- A previous `data-seed/` exists but the data shape changed (new entity types, new upstream service).

Do NOT run autonomously after code changes — this is a setup tool, not a per-commit safety net.

---

## Phase 0: Preflight

### 0.1 — Confirm working directory

The user must invoke from inside the target repo (the repo HawkScan will scan):

```bash
test -d .git || echo "NOT-A-REPO"
pwd
```

If not a git repo, ask the user to `cd` to the target repo and re-invoke.

### 0.2 — Confirm `hawk perch seed` is available

```bash
hawk perch seed --help >/dev/null 2>&1 || echo "NO-SEED-COMMAND"
```

If unavailable, **PUNT**: tell the user their `hawk` version doesn't include `hawk perch seed` yet and to upgrade (`brew upgrade stackhawk/cli/hawk`, or download from https://download.stackhawk.com/hawk). Do NOT fall back to hand-authoring seed data — the seed methodology now lives in the `hawk` CLI.

### 0.3 — Check for existing data-seed

```bash
test -d data-seed && echo "EXISTS"
```

If `data-seed/` exists, ask the user whether to **augment**, **replace** (`mv data-seed data-seed.bak-$(date +%s)`), or **cancel**.

---

## Phase 1: Run `hawk perch seed`

Spawn the command as a long-running subprocess with structured events:

```bash
hawk perch seed --events json --app-host "$APP_HOST"
```

- `--app-host` — the target app's URL. Ask the user if not known (e.g. `http://localhost:8080`).
- `--output <dir>` — optional; directory to write `data-seed/` under (defaults to the current directory).
- `--mcp-port <n>` — optional; port of the running HSTE daemon the seed loop talks to (follow the command's own help/output for the daemon prerequisite).

**stdout** carries JSONL phase events (one JSON object per line — parse with `jq -c .`). **stderr** carries human-readable text (banners, prompts, errors) — tee it for the user, don't discard it.

Consume the phase events and relay concise progress to the user:

| `phase` | Meaning |
|---|---|
| `starting` | Seed run beginning |
| `extracting` | Reading repo signals (storage kind, routes, schema) |
| `synthesizing` | Designing the minimum seed entities |
| `validating` | Checking the generated manifest |
| `finalizing` | Writing `data-seed/` artifacts |
| `done` | Complete; payload includes `success` and `outputDir` |

If a phase event prompts for user input or review, surface it and wait for the user before continuing. If the process exits non-zero, report the `done` event's message (plus relevant stderr) and stop — do not improvise seed artifacts.

---

## Phase 2: Handoff

On a `done` event with `success: true`:

```
Data seed complete. Created under <outputDir>:
- data-seed/manifest.yaml
- per-service seed scripts
- .data-seed-credentials.env (gitignored)

Next steps:
1. Review data-seed/manifest.yaml and the per-service files.
2. Start your stack, then replay the manifest (see data-seed/README.md if present).
3. Invoke hawkscan to configure stackhawk.yml — it reads .data-seed-credentials.env automatically.
```

Commit reminder:

```bash
git add data-seed/ .gitignore
git commit -m "chore: add data seed artifacts for HawkScan"
```

`.data-seed-credentials.env` is gitignored and must not be committed.

---

## Boundaries with hawkscan

This skill never writes or modifies `stackhawk.yml`, selects authentication recipes, or creates Apps/Envs on the StackHawk platform. The handoff is one file: `.data-seed-credentials.env`. Hawkscan reads it and plugs the values into whatever auth recipe it selects.