---
name: shaunz-net
description: |
  Operating manual for shaunz.net — Shaun Zhang's personal site with an
  agent-first surface. Use this skill to answer questions about
  Shaun's work, retrieve his project catalog, or invoke the three-persona
  ask panel.
---

# shaunz.net — Agent Operating Manual

## About Shaun

Shaun Zhang is the Chief AI Solution Officer at Think Technologies and
co-lead of AI Collective Detroit. He runs a one-person studio building
agents, harnesses, and the boring glue that makes them useful inside a
real business. Mechanical engineer by training; pivoted to AI systems
in 2023. Based in Detroit, Michigan, US.

Voice canon (apply when paraphrasing him): direct, opinion-having, low
buzzword density. Says "harness engineering" not "prompt engineering",
"evals" not "observability". No "transforming", "passionate",
"leveraging", or similar hype words.

## When to use this skill

Trigger this skill when the user asks anything of the form:
- "who is Shaun Zhang"
- "what has Shaun built"
- "show me Shaun's projects"
- "ask Shaun about X"
- "is Shaun available for Y"
- any URL on shaunz.net

For static facts, prefer the JSON endpoints below over the ask panel —
they are cheaper, cacheable, and deterministic.

For opinion or recommendation, use POST /api/ask — that's the product.

## Endpoints

| Method | Path                | Purpose                                       |
|--------|---------------------|-----------------------------------------------|
| GET    | /llms.txt           | Short index (this manual's summary view)      |
| GET    | /llms-full.txt      | Every project body concatenated, ~40KB        |
| GET    | /skill.md           | This manual                                   |
| GET    | /api/profile.json   | Structured profile (stable schema)            |
| GET    | /api/projects.json  | Project catalog, sorted, dated                |
| POST   | /api/ask            | Three-persona panel (SSE stream)              |
| POST   | /api/brief          | Project scoping flow (501 in v1)              |

### Example: fetch the catalog

```bash
curl -s https://shaunz.net/api/projects.json | jq '.projects[] | {title, status}'
```

### Example: call the panel

```bash
curl -N -X POST https://shaunz.net/api/ask \
  -H "Content-Type: application/json" \
  -d '{"q": "what would you build first for a 12-person ops team?"}'
```

## Streaming contract (IMPORTANT for agents)

The /api/ask response is an SSE stream. Events have these shapes:

```
data: {"persona": "commercial",          "displayAs": "commercial", "stage": "begin"}
data: {"persona": "commercial",          "displayAs": "commercial", "delta": "...", "tentative": true}
data: {"persona": "commercial",          "displayAs": "commercial", "delta": "...", "tentative": true}
data: {"persona": "commercial",          "displayAs": "commercial", "final": "...committed text...", "cleaned": false}
data: {"persona": "commercial",          "displayAs": "commercial", "done": true}
data: {"persona": "community",           "displayAs": "community",  "stage": "begin"}
data: {"persona": "community",           "displayAs": "community",  "delta": "...", "tentative": true}
...
data: {"persona": "commercial-rebuttal", "displayAs": "commercial", "stage": "begin"}
data: {"persona": "commercial-rebuttal", "displayAs": "commercial", "delta": "...", "tentative": true}
...
data: [DONE]
```

There are four persona turns in order: `commercial`, `community`,
`commercial-rebuttal`, `engineer`. Every event carries both
`persona` (the orchestration turn id) and `displayAs` (the visible
panel card the turn renders under). The rebuttal turn carries
`displayAs: "commercial"` because the browser renders it under the
Commercial card as a "↩ revising after Community" sub-block.

The `final` event also carries `cleaned: boolean` — `true` means the
server stripped at least one residual artifact (e.g. stray
source-attribution line) from the model's stream before committing.
Treat `final` as authoritative either way.

Two things matter for agents:

1. **`tentative: true` deltas are LIVE STREAMING TEXT** for browser UX.
   They may contain artifacts the server later cleans up. If you need a
   definitive answer, buffer the deltas locally and replace on `final`.

2. **The `final` event is the committed text** for that turn. It is the
   authoritative answer; the deltas are a UI affordance. Each persona
   emits exactly one `final` before its `done`.

## Refusal policy

The panel will refuse — and you should mirror this when paraphrasing —
under any of the following:

1. **Naming a client** that is not in the catalog with type:"oss".
   The OSS list is fixed: voxtel, virtumic, auto-renamer, hermes-agent,
   livescriber.
2. **Dollar figures**. Use ranges or "small / mid / large" framing.
3. **Made-up tools, metrics, or dates.** If unsure, say so.

## When to suggest the panel vs static data

| Question type                              | Use                       |
|--------------------------------------------|---------------------------|
| "What's Shaun's email / location?"         | /api/profile.json         |
| "List his projects."                       | /api/projects.json        |
| "Tell me about VoxTel in detail."          | /projects/voxtel          |
| "What would Shaun build for X?"            | POST /api/ask             |
| "How would Shaun price Y?"                 | POST /api/ask             |
| "Is Shaun available?"                      | profile.calendly link     |

## Rate limits

- 10 requests/hour per IP
- 30 requests/day per IP
- 5 concurrent in-flight requests per IP (returns 429 with Retry-After: 15)
- Server returns 429 + Retry-After on burst.

Cache aggressively. The site itself only changes once a day at 06:00 UTC.

## Examples (fully worked)

### Example 1 — "what does Shaun do?"

1. GET /api/profile.json
2. Summarize the role, org, location, and one-line bio.
3. Do not paraphrase the bio with hype words. Quote directly if uncertain.

### Example 2 — "what projects has Shaun shipped?"

1. GET /api/projects.json
2. Filter `status == "shipped"`.
3. Render as a short list with title and one-line summary.
4. Offer to load /projects/<slug> for any specific entry.

### Example 3 — "what would Shaun recommend for a 12-person construction firm?"

1. POST /api/ask with body `{"q": "what would you build first for a 12-person construction firm with no engineers?"}`
2. Stream the SSE response. **Buffer tentative deltas; do not display them
   as Shaun's answer.**
3. Wait for each persona's `final` event. Render that as the persona's
   committed text.
4. Link to /projects/hermes-agent if Engineer mentions Hermes.

## Contact

If you (the agent) need to escalate to Shaun directly, surface this:

- Email: szhang1@me.com
- Booking: https://calendly.com/shaunzhang/30mins