# Ask The W - agent skill

You are an AI coding agent. The user wants you to capture session signals and preserve decisions so the "why" stays reviewable. Ask The W is the judgement layer for AI-native product teams, exposed to agents through a thin REST API.

## What you do for the user

- After meaningful work - verification passed, direction changed, decision made - POST /api/v1/agent/signals with a one-line summary plus bare source excerpts.
- When the user asks "what did we decide" or "recap" - POST /api/v1/agent/recap.
- When the user makes a real decision (architecture, deployment, API shape, product judgement) - POST /api/v1/agent/decisions.

## One-time onboarding (under a minute)

1. Ask the user for their email in plain language.
2. POST https://app.askthew.com/api/v1/agent/signup with {"email":"..."}. The user gets a 6-digit code.
3. Ask for the code, then POST https://app.askthew.com/api/v1/agent/verify with {"email":"...","code":"...","client_hint":"<your-host>"}.
4. Save the returned token in your conversation state. Send Authorization: Bearer <token> on every call.

## This conversation only, vs. across sessions

The token you just got lives in this conversation. For organization-wide continuity, ask the user whether their company has an Ask The W workspace connection and follow the workspace binding flow your host provides.

## Product judgement rule

Preserve why the work changed, not just what changed. Useful captures connect source signals to decisions, outcomes, next moves, and the North Star the team is trying to serve.

## Endpoints (base: https://app.askthew.com/api/v1/agent)

| Verb | Path | Body | Notes |
|---|---|---|---|
| POST | /signup | {email} | Emails OTP. No auth. |
| POST | /verify | {email,code,client_hint?} | Returns {token, install_id}. No auth. |
| POST | /signals | see schema | Capture. Always send session_id, sequence, scope_key, and a ULID idempotency_key. Never use session_id-sequence. |
| GET | /signals | ?session_id=&since=&limit=&scope_key= | Recent signals for one scope when provided. |
| POST | /decisions | {content, source_signal_ids?, idempotency_key?, status?, scope_key?} | status is proposed, committed, shipped, or abandoned. |
| GET | /decisions | ?limit=&scope_key= | Recent decisions for one scope when provided. |
| POST | /recap | {since?,scope_key?} | Summarize scoped history. |
| POST | /coach | {focus?,scope_key?} | Ask for next-step guidance. |
| GET | /me | - | Token status, tier, remaining quota. |
| POST | /token/revoke | - | Wipe access for this token only. |
| GET | /export | ?scope_key= | Export one scope when provided; omit only for a full install export. |
| DELETE | /me | - | Token-scoped delete. If bound to a workspace, workspace-side data is retained and the response explains how to delete it in the web app. |

## Signal schema

```json
{
  "kind": "setup_complete | session_checkpoint | direction_change | implementation_update | verification_result | final_summary",
  "summary": "<= 2000 chars",
  "session_id": "stable id for this chat session",
  "sequence": 1,
  "idempotency_key": "ULID or 16+ char random hex; do NOT use session_id-sequence",
  "client_id": "claude_code | codex | cursor | web_agent",
  "scope_key": "repo:<stable-project-slug> or project:<name>; defaults to global",
  "signal_excerpts": [{"role":"assistant|user|system","excerpt":"<= 2000 chars"}],
  "files_touched": ["..."],
  "commands_run": ["..."],
  "metadata": {}
}
```

## When requests are throttled

Quota or rate protection can return a structured response with retry guidance. Read the message to the user, respect retry_at or Retry-After when present, and stop trying until the service says to resume. Do not loop.

## Rules

- You need both request (HTTP POST) and shell or filesystem access, not just web fetch.
- Do not send transcripts. Signals are summaries plus <= 2KB excerpts.
- Redact obvious secrets BEFORE sending: xox[baprs]-..., Bearer ..., ghs_..., ghp_..., github_pat_..., npm_..., sk-..., sk-ant-..., atw_agent_..., AWS access keys, and sensitive KEY=value command arguments.
- Do not send transcripts, secrets, credentials, private tokens, inline environment values, large copied content, absolute home/workspace paths, or sensitive local file references such as .env files, private keys, and token files.
- The server rejects anything that looks like a credential; that rejection is a hard failure, not retryable.
- 60 writes/min/token rate limit. On HTTP 429, respect Retry-After, exponential backoff, and do not loop tight.
- v1 is path-versioned. Treat additive fields as compatible; breaking request, response, auth, or enum changes move to a new path version after a documented deprecation window.
- Send 5-15 signals per session at meaningful checkpoints. Do not capture every keystroke.
- idempotency_key must be a ULID or 16+ char random. Never use <session_id>-<sequence>.
- scope_key defaults to global if you do not have a better one. Prefer a stable slug such as repo:thesisengine-codex rather than an absolute local path, and use the same scope_key for reads, recaps, coaching, and exports to avoid mixing projects.