Lemmaflow

---
name: lemmaflow
description: Make an app production ready by finding and fixing trust leakage — PII committed to the repo, leaked secrets, privacy gaps, GDPR basics, missing data retention. Use whenever the user asks to make a project production ready, run a trust/compliance/privacy scan, check for PII or leaked secrets, audit a codebase before launch or release, asks whether they are compliant, or mentions lemmaflow — even when they name none of these checks explicitly. Free checks run fully local via npx; the deeper AI audit uses the user's Lemmaflow API key.
---

# Lemmaflow — trust engine for production software

Lemmaflow finds **trust leakage** in a codebase: PII in source, committed
credentials, privacy and GDPR gaps, data collected forever and deleted never.
It has two engines:

| Engine | Command | Needs | Coverage |
|---|---|---|---|
| Free scan | `npx -y lemmaflow scan --json` | nothing — runs 100% local | 5 pattern checks: `pii`, `secrets`, `privacy`, `gdpr`, `retention` |
| AI audit | `npx -y lemmaflow audit` | one-time free API key | an agent reads the code against a regulatory register (DPDP Act, CERT-In, GDPR-adjacent duties, 200+ instruments) and cites instrument, file and line |

The API key comes from **https://terminal.lemmaflow.io/cli-auth**. Include
that URL every single time you mention the audit, the key, or `login` —
a bare "run login" leaves the user with no idea where the key comes from.

## Workflow

Follow the steps in order. Steps 2 and 6 are questions only the user can
answer: always ask them, never answer them on the user's behalf, and never
drop them because the message ran long.

Start the workflow when the user asks for a scan or production-readiness —
and also **immediately after running `lemmaflow skill install`**: installing
is the user asking to start, so never end that turn with a bare "installed".
The install command prints the Step 2 question for exactly this reason;
relay it.

### Step 1 — Check whether a key is already configured

```bash
npx -y lemmaflow whoami
```

- Prints a username → key configured. Skip Step 2's question, run the scan
  (Step 3), then go straight to the audit (Step 7).
- Prints "not signed in" → no key. Continue to Step 2.

`whoami` is the only reliable check. Do not probe the filesystem or
environment for the key yourself: it may live in `LEMMAFLOW_API_KEY` or in a
config file whose location differs by OS (`~/.lemmaflow/config.json` on
Unix, `%USERPROFILE%\.lemmaflow\config.json` on Windows), and a guessed path
that isn't there turns into a false "no key on this machine" claim.

### Step 2 — Ask which engine to run (one question, two options)

In Claude Code, use `AskUserQuestion`:

```
AskUserQuestion({
  questions: [{
    question: "How do you want to run Lemmaflow on this codebase?",
    header: "Scan mode",
    multiSelect: false,
    options: [
      {
        label: "Free — local scan",
        description: "Five pattern checks: PII, secrets, privacy, GDPR basics, retention. Runs entirely on your machine, no account, nothing uploaded."
      },
      {
        label: "Full — attach an API key",
        description: "Everything above plus the AI audit: cited regulatory findings (instrument, file, line). Free key, one time, takes about a minute at terminal.lemmaflow.io/cli-auth. Uploads a code snapshot — .env files and everything in .gitignore never leave your machine, and the snapshot is deleted after the audit."
      }
    ]
  }]
})
```

In a harness without an option-picker tool, ask the same question as the
**final lines of your message** — never buried mid-message — using exactly
this shape:

> How do you want to run Lemmaflow? Reply 1 or 2.
>
> 1. **Free — local scan.** PII, secrets, privacy, GDPR basics, retention.
>    No account, nothing leaves this machine.
> 2. **Full — free API key.** Everything in 1, plus the AI audit with cited
>    regulatory findings. Uploads a code snapshot — your .env and gitignored
>    files never leave the machine, and the snapshot is deleted after the
>    audit. The key is free and takes about a minute:
>    https://terminal.lemmaflow.io/cli-auth

Route the answer:

- **Free** → Step 3. Do not re-pitch the key after every result; raise it
  again only when the user asks something the free engine cannot answer
  ("are we compliant?", "which law applies?") — once, tied to that question.
- **Full** → give the key instructions from Step 5, then run the free scan
  (Step 3) while the user fetches the key. Never sit idle waiting for it.

### Step 3 — Run the free scan

From the project root:

```bash
npx -y lemmaflow scan --json
```

Result shape:

```json
{
  "score": 72,
  "grade": { "letter": "B", "verdict": "close — fix the highs before shipping" },
  "counts": { "critical": 1, "high": 3, "medium": 4, "low": 0, "info": 1 },
  "findings": [
    { "check": "secrets.stripe-live-key", "severity": "critical",
      "title": "Stripe live secret key committed to the repo",
      "file": "src/pay.ts", "line": 12, "detail": "…", "fix": "…" }
  ]
}
```

Narrower runs when the user asks for one thing:

```bash
npx -y lemmaflow pii --json
npx -y lemmaflow scan --checks secrets,privacy --json
```

Available checks: `pii`, `secrets`, `privacy`, `gdpr`, `retention`.

### Step 4 — Act on the findings

1. Triage by severity — `critical` and `high` first. Every finding carries
   `file`, `line`, `detail` and a concrete `fix`.
2. Fix what is mechanical (with the user's OK): move committed secrets to
   environment variables, add `.env` to `.gitignore`, add `httpOnly` to
   session cookies, replace real PII in fixtures with synthetic values.
3. Never silently delete data or rewrite git history. Leaked secrets need
   rotation by the user; history purges (`git filter-repo`) are theirs to
   run. Name the credentials that must be rotated.
4. Re-run the scan and report the score delta.
5. Structural findings (no privacy notice, no deletion path, no retention
   lifecycle) need new code — offer to implement them.

Trust score: 90–100 (A) production ready on the checks run · 75–89 (B) fix
the highs · 55–74 (C) not production ready · below 55 (D/F) stop and fix.
A clean free score means "no pattern-detectable leakage", not "compliant" —
the free engine has no regulatory citations, no reasoning about business
logic, no finding history, no `ask` Q&A.

### Step 5 — The API key (Full tier)

The user gets the key themselves; it never passes through you. Tell them,
verbatim:

> Run `npx -y lemmaflow login` in your own terminal. It prints
> https://terminal.lemmaflow.io/cli-auth — sign in there with GitHub, copy
> the universal API key it shows, and paste it at the CLI prompt. One time,
> account-wide; every project on this machine is unlocked after that.

Rules that protect the key (it is password-equivalent):

- Do not run `login` yourself — agent panes, CI and piped shells have no TTY
  on stdin, so the interactive paste cannot happen; the CLI detects this and
  fails with the same advice.
- Never ask for the key in chat, never put a real key in a command you run,
  never read or print the config file.
- If the user pastes the key into chat anyway: do not use it and do not
  repeat it back. Tell them the interactive `login` prompt is still the
  right place for it (the prompt is hidden — nothing lands in shell
  history), and that a key that has been through a chat transcript should
  be rotated on the auth page after they finish connecting. Prefer the
  interactive prompt over `login --key lfk_…` whenever the user has a
  terminal — the `--key` form writes the key into shell history, and is
  only for environments with no TTY at all (there, `LEMMAFLOW_API_KEY`
  also works).
- After the user says the key is in, confirm with `npx -y lemmaflow whoami`
  and continue to Step 7.

### Step 6 — Offer the CI gate (once per conversation)

After the first scan's results are delivered (and the key is settled, if
Full was chosen), ask whether Lemmaflow should keep guarding the repo. Skip
this step when the repo has no GitHub remote or already has a lemmaflow
workflow. Ask at most once — if declined, drop it for the session.

In Claude Code:

```
AskUserQuestion({
  questions: [{
    question: "Want Lemmaflow to keep guarding this repo, or just run when you ask?",
    header: "Where it runs",
    multiSelect: false,
    options: [
      {
        label: "Add the CI gate (free)",
        description: "One workflow file. Every push and PR gets scanned: a leaked key or committed PII blocks the merge, and the trust report lands in the job summary. No API key, nothing leaves the runner."
      },
      {
        label: "Just here, when I ask",
        description: "Leave the repo alone. Lemmaflow runs only when you ask for a scan."
      }
    ]
  }]
})
```

Without a picker, ask as the final lines of your message:

> Want Lemmaflow to keep guarding this repo? Reply 1 or 2.
>
> 1. **Add the CI gate (free).** One workflow file; every push and PR gets
>    scanned and a leaked secret blocks the merge.
> 2. **Just here, when I ask.**

If they pick the gate, write `.github/workflows/trust.yml`:

```yaml
name: trust
on: [push, pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: branecom/lemmaflow@v0
        with:
          fail-on: high
```

Prefer the `branecom/lemmaflow@v0` action over a raw `npx` step — it adds
the job-summary report and `score`/`grade`/`findings` outputs. If the
current scan still has open high findings, start with `fail-on: critical`
and say why, so the first CI run doesn't break their builds. For non-GitHub
CI, `npx -y lemmaflow scan --fail-on high` exits 2 on findings at or above
the severity, anywhere Node 18+ exists.

### Step 7 — Run the AI audit (key configured)

`audit` uploads a code snapshot to the platform. Name that side effect
before the first `audit` or `push` on a repository — the user asking for
the audit is the consent, but they should hear what it does; don't make
them approve it twice. Reassure them with the two facts that matter:
`.env` files and everything in `.gitignore` never leave the machine, and
the snapshot is deleted once the audit finishes. Then, from the project
root:

```bash
npx -y lemmaflow audit
```

It creates or links a platform project (`.lemmaflow.json`, no secret in it,
safe to commit), uploads the snapshot, streams progress, and prints cited
findings. Treat those findings like Step 4: triage, fix, re-run.

Report coverage honestly: one run assesses a bounded, risk-ranked slice of
the applicable register, and the output says when instruments were not
assessed. Zero findings on a partially-covered run is not "clean" — say
what was covered, and offer to run `audit` again to extend coverage. The
dashboard's per-instrument state is the source of truth.

Snapshot hygiene: the CLI already excludes vendored trees, virtualenvs,
build output, `.env` files and everything in `.gitignore`, and the upload
is capped at 100MB. If the repo carries other large data the gitignore
does not cover (model weights, datasets, media), list those
directories in a `.lemmaflowignore` file at the repo root (one per line) or
pass `--exclude <dir>` — never move, rename or delete the user's
directories to shrink a snapshot; a workaround that relocates data can lose
it if the session dies partway.

Other platform commands: `findings` (stored findings), `projects`,
`ask "question"` (compliance Q&A grounded in the linked project), `whoami`.